[PR #4095] [MERGED] feat(cli): access team workspace collections and environments #4663

New issue

Closed

opened 2026-03-17 02:10:45 +03:00 by kerem · 0 comments

kerem commented

2026-03-17 02:10:45 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/hoppscotch/hoppscotch/pull/4095
Author: @jamesgeorge007
Created: 5/30/2024
Status: ✅ Merged
Merged: 6/27/2024
Merged by: @jamesgeorge007

Base: next ← Head: feat/cli-access-team-workspaces

📝 Commits (10+)

25c704a feat: access team workspace collections and environments from the CLI
56a2c51 test: add unit tests
1a5295a test: e2e & unit test suite updates
2f452a7 fix: ensure custom error codes take precedence
0af39d3 chore: add JSDoc comments
a34456b chore: fix spelling
36eb964 refactor: add handler for non-axios errors
2f64f75 fix: prevent server URL from being displayed as undefined with the error message
4824a6b refactor: eliminate redundancy
de64e58 refactor: update getResourceContents helper function signature

📊 Changes

48 files changed (+17364 additions, -13197 deletions)

View changed files

➖ packages/hoppscotch-cli/jest.config.ts (+0 -193)
➖ packages/hoppscotch-cli/jest.setup.ts (+0 -1)
📝 packages/hoppscotch-cli/package.json (+3 -5)
➕ packages/hoppscotch-cli/setupFiles.ts (+15 -0)
➖ packages/hoppscotch-cli/src/__tests__/commands/test.spec.ts (+0 -345)
➕ packages/hoppscotch-cli/src/__tests__/e2e/commands/test.spec.ts (+509 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/coll-v1-req-v0.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/coll-v1-req-v1.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/coll-v2-req-v2.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/coll-v2-req-v3.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/collection-level-auth-headers-coll.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/env-flag-tests-coll.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/fails-coll.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/malformed-coll-2.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/malformed-coll.json (+0 -0)
➕ packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/multiple-child-collections-auth-headers-coll.json (+655 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/notjson-coll.txt (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/passes-coll.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/pre-req-script-env-var-persistence-coll.json (+0 -0)
📝 packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/req-body-env-vars-coll.json (+0 -0)

...and 28 more files

📄 Description

Description

This PR aims at bringing support for accessing collections and environments within team workspaces (support for personal workspace will be brought down the line) from the CLI by supplying their respective IDs. The following updates are made to the test command:

The test command and the -e, --env flag now support specifying an ID in addition to the file path.
A new --token flag is added that takes in a personal access token for authorized access to the above resources.
By default, the data is fetched from the Hoppscotch cloud instance. Alternatively, an SH instance can be specified using the new --server flag.
```
hopp test <file_path_or_id> -e <file_path_or_id> --token <access_token> --server <server_url>
```

Error codes

There are various scenarios where a workspace access attempt can fail under which the following error codes will be displayed in the CLI:

TOKEN_EXPIRED - The supplied access token <access-token> via the --token flag has expired.
TOKEN_INVALID - The specified access token <access-token> via the --token flag is invalid or might have been deleted.
INVALID_ID - The user can supply a file path or ID for a collection (file path argument for the test command) / environment (-e, --env, flag for the test command). If the ID was provided and the above error corresponds to the case in which an invalid ID is supplied or the resource is inaccessible to the user, being from a team that the user isn't part of. In the case of a file path, the above error corresponds to a case in which the supplied file path doesn't exist. We're clubbing both cases since there isn't a way to distinguish between b/w IDs and non-existent file paths if the network call aimed at workspace access fails.
INVALID_SERVER_URL

There are multiple cases in which this error can happen:
- If the supplied server URL doesn't have a valid path under /v1/access-tokens/{collection/environment}/{path/id} with the network call resulting in a 404.
- If the received content type from the response is not application/json, safeguarding against the case where the network call doesn't fail where the route is not valid as above and checking against the content type. For instance, supplying the FE instance URL.
- The supplied server URL doesn't conform to URL semantics (received ERR_INVALID_URL as the error code from the network call). For instance, missing a protocol (e.g., http:// or https://), having an invalid structure, or containing illegal characters.
- Couldn't find the server because the domain name couldn't be resolved (received ENOTFOUND as the error code from the network call). For instance, a typo in the domain name.
SERVER_CONNECTION_REFUSED - Found the server, but the server refused to connect (received ECONNREFUSED as the error code from the network call).

Changes

New flag additions/updates to the test command.
Addition of new error codes (mentioned above) with the respective error messages associated with various scenarios where workspace access can fail.
Compiles the business logic about accessing resource contents via the supplied file path/workspace ID in a new getResourceContents() helper function under ~/utils/getters.ts. It checks for the existence of a file path corresponding to the supplied value and proceeds with the network call if it isn't the case.
The response received from the network call (fetching collection/environments from a workspace), is a format different from the internal HoppCollection / HoppEnvironment formats, and requires transformation before further processing. New helper functions transformWorkspaceCollection() & transformWorkspaceEnvironment() are added under ~/utils/workspace-access.ts.
Update the readJsonFile helper function under ~/utils/mutators.ts to include an additional parameter fileExistsInPath used to throw an error if the file doesn't exist in path. A check for the same that existed previously is removed in favor of the same performed at an earlier point (proceed with the network call if there isn't a valid file path corresponding to the supplied path/ID).
The test runner is migrated from Jest to Vitest since it supports ESM out of the box.
New e2e test case added with multiple child collections at each level inheriting/overriding authorization and headers set at the parent level, ref. The existing case included a fixture (renamed to follow a consistent convention) with deeply nested collections. This new addition ensures the implementation accounts for multiple child collections at each level.
Directory hierarchy updates for the test suite, better separation of concerns with e2e tests moved under __tests__/e2e and unit tests under __tests__/unit with the respective test data maintained under fixtures for both directories. The pre-existing unit tests under __tests__/functions are to be revisited separately (Tracked in HFE-326) and moved under __tests__/unit.

Closes HFE-502 HFE-503.

Steps to verify (SH)

Spin up the selfhost-web dev server and the BE container locally.
Obtain a new personal access token to access the workspace resources. It can be done via the UI if checking out to #4094. Alternatively, send a post request to the http://<localhost_server_url>/v1/access-tokens/create endpoint with the following body:
```
{
  "label": "<token-label>",
  "expiryInDays": 30
}
```
The above endpoint is behind JWT Auth guards and please ensure to send along the relevant cookies (access_token).
Choose a collection to run via the CLI or create one if none exists.
#4141 brings about the support for obtaining the collection/environment ID straightaway from the UI. The CLI command to run a particular collection can be obtained if checking out to the above branch or following the steps below. Grab the collection ID (match the name against the title field from the response within the data.rootCollectionsOfTeam field and pick the corresponding id field value) of interest from the RootCollectionsOfTeam GQL query.
```
query RootCollectionsOfTeam($teamID: ID!, $cursor: ID) {
  rootCollectionsOfTeam(teamID: $teamID, cursor: $cursor) {
    id
    title
    data
  }
}
```

Navigate to the hoppscotch-cli package path locally and run pnpm build. Run the collection via:

bin/hopp.js test <copied_collection-id> --token <access_token> --server <localhost_server_url>

bin/hopp.js can be replaced with hopp if a symlink is created via pnpm link.

Replace placeholders with the values obtained in the previous steps. localhost_server_url defaults to http://localhost:3170.

Similarly, if running a collection that requires an environment, grab the environment ID (match the name against the name field from the response within the data.team.teamEnvironments field and pick the corresponding id field value) from the GetTeamEnvironments GQL query.
```
query GetTeamEnvironments($teamID: ID!) {
  team(teamID: $teamID) {
    teamEnvironments {
      id
      name
      variables
      teamID
    }
  }
}
```

Run the collection supplying the environment ID:

bin/hopp.js test <copied_collection-id> -e <copied_environment_id> --token <access_token> --server <localhost_server_url>

Both file path and ID can be supplied while specifying an access token. Try out different combinations and the different error scenarios mentioned above.

To verify the changes against the cloud BE, supply https://stage-api.hoppscotch.io along with the --server flag and obtain the collection/environment IDs from the cloud staging instance.

Checks

My pull request adheres to the code style of this project
My code requires changes to the documentation
I have updated the documentation as required
All the tests have passed

Note to reviewers

E2e additions for the workspace access behavior (tests including the usage of --token & --server flags) are skipped for now. It'll be enabled once a proper e2e test environment is set up locally. Unit tests are in place for the new functionality added.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/hoppscotch/hoppscotch/pull/4095 **Author:** [@jamesgeorge007](https://github.com/jamesgeorge007) **Created:** 5/30/2024 **Status:** ✅ Merged **Merged:** 6/27/2024 **Merged by:** [@jamesgeorge007](https://github.com/jamesgeorge007) **Base:** `next` ← **Head:** `feat/cli-access-team-workspaces` --- ### 📝 Commits (10+) - [`25c704a`](https://github.com/hoppscotch/hoppscotch/commit/25c704ae4f3d6fc5bfa076920a19b7b545ba0468) feat: access team workspace collections and environments from the CLI - [`56a2c51`](https://github.com/hoppscotch/hoppscotch/commit/56a2c5176010ee82333b46bcccdf11415eece02f) test: add unit tests - [`1a5295a`](https://github.com/hoppscotch/hoppscotch/commit/1a5295a0475be21546b6d22017ae07772c6de74c) test: e2e & unit test suite updates - [`2f452a7`](https://github.com/hoppscotch/hoppscotch/commit/2f452a7abb08f4c06b49304e74a09695aa58d608) fix: ensure custom error codes take precedence - [`0af39d3`](https://github.com/hoppscotch/hoppscotch/commit/0af39d328a34caa391d037085e44f90eb2c0d8cf) chore: add JSDoc comments - [`a34456b`](https://github.com/hoppscotch/hoppscotch/commit/a34456b0c61e5a8a3708774962944a9cd2d56f91) chore: fix spelling - [`36eb964`](https://github.com/hoppscotch/hoppscotch/commit/36eb964ca5d294d9ab90983cb74c743006476abc) refactor: add handler for non-axios errors - [`2f64f75`](https://github.com/hoppscotch/hoppscotch/commit/2f64f75252a0f4676fd315f9f1a0827916b34694) fix: prevent server URL from being displayed as `undefined` with the error message - [`4824a6b`](https://github.com/hoppscotch/hoppscotch/commit/4824a6b477e2211a738531af47418b7e7bd7be05) refactor: eliminate redundancy - [`de64e58`](https://github.com/hoppscotch/hoppscotch/commit/de64e5874f0ff47cc7d70f6e1e4d2bfc50616fc8) refactor: update `getResourceContents` helper function signature ### 📊 Changes **48 files changed** (+17364 additions, -13197 deletions) <details> <summary>View changed files</summary> ➖ `packages/hoppscotch-cli/jest.config.ts` (+0 -193) ➖ `packages/hoppscotch-cli/jest.setup.ts` (+0 -1) 📝 `packages/hoppscotch-cli/package.json` (+3 -5) ➕ `packages/hoppscotch-cli/setupFiles.ts` (+15 -0) ➖ `packages/hoppscotch-cli/src/__tests__/commands/test.spec.ts` (+0 -345) ➕ `packages/hoppscotch-cli/src/__tests__/e2e/commands/test.spec.ts` (+509 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/coll-v1-req-v0.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/coll-v1-req-v1.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/coll-v2-req-v2.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/coll-v2-req-v3.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/collection-level-auth-headers-coll.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/env-flag-tests-coll.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/fails-coll.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/malformed-coll-2.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/malformed-coll.json` (+0 -0) ➕ `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/multiple-child-collections-auth-headers-coll.json` (+655 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/notjson-coll.txt` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/passes-coll.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/pre-req-script-env-var-persistence-coll.json` (+0 -0) 📝 `packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/req-body-env-vars-coll.json` (+0 -0) _...and 28 more files_ </details> ### 📄 Description ### Description This PR aims at bringing support for accessing collections and environments within team workspaces (support for personal workspace will be brought down the line) from the CLI by supplying their respective IDs. The following updates are made to the `test` command: - The `test` command and the `-e, --env` flag now support specifying an ID in addition to the file path. - A new `--token` flag is added that takes in a personal access token for authorized access to the above resources. - By default, the data is fetched from the Hoppscotch cloud instance. Alternatively, an SH instance can be specified using the new `--server` flag. ```sh hopp test <file_path_or_id> -e <file_path_or_id> --token <access_token> --server <server_url> ``` ### Error codes There are various scenarios where a workspace access attempt can fail under which the following error codes will be displayed in the CLI: - `TOKEN_EXPIRED` - The supplied access token `<access-token>` via the `--token` flag has expired. - `TOKEN_INVALID` - The specified access token `<access-token>` via the `--token` flag is invalid or might have been deleted. - `INVALID_ID` - The user can supply a file path or ID for a collection (file path argument for the `test` command) / environment (`-e, --env,` flag for the `test` command). If the ID was provided and the above error corresponds to the case in which an invalid ID is supplied or the resource is inaccessible to the user, being from a team that the user isn't part of. In the case of a file path, the above error corresponds to a case in which the supplied file path doesn't exist. We're clubbing both cases since there isn't a way to distinguish between b/w IDs and non-existent file paths if the network call aimed at workspace access fails. - `INVALID_SERVER_URL` There are multiple cases in which this error can happen: - If the supplied server URL doesn't have a valid path under `/v1/access-tokens/{collection/environment}/{path/id}` with the network call resulting in a `404`. - If the received content type from the response is not `application/json`, safeguarding against the case where the network call doesn't fail where the route is not valid as above and checking against the content type. For instance, supplying the FE instance URL. - The supplied server URL doesn't conform to URL semantics (received `ERR_INVALID_URL` as the error code from the network call). For instance, missing a protocol (e.g., `http://` or `https://`), having an invalid structure, or containing illegal characters. - Couldn't find the server because the domain name couldn't be resolved (received `ENOTFOUND` as the error code from the network call). For instance, a typo in the domain name. - `SERVER_CONNECTION_REFUSED` - Found the server, but the server refused to connect (received `ECONNREFUSED` as the error code from the network call). ### Changes - New flag additions/updates to the `test` command. - Addition of new error codes (mentioned above) with the respective error messages associated with various scenarios where workspace access can fail. - Compiles the business logic about accessing resource contents via the supplied file path/workspace ID in a new `getResourceContents()` helper function under [~/utils/getters.ts](https://github.com/hoppscotch/hoppscotch/pull/4095/files#diff-484af5d66255ca92b321d69e2ad27f54a0323413d566793f2a117e15cceb3261). It checks for the existence of a file path corresponding to the supplied value and proceeds with the network call if it isn't the case. - The response received from the network call (fetching collection/environments from a workspace), is a format different from the internal `HoppCollection` / `HoppEnvironment` formats, and requires transformation before further processing. New helper functions `transformWorkspaceCollection()` & `transformWorkspaceEnvironment()` are added under [~/utils/workspace-access.ts](https://github.com/hoppscotch/hoppscotch/pull/4095/files#diff-5aeed27b9a70e946d1ab455e390bb090e261ddcbeba51bb01fa6f19f82ee8afd). - Update the `readJsonFile` helper function under [~/utils/mutators.ts](https://github.com/hoppscotch/hoppscotch/pull/4095/files#diff-fccb5e9c3967b37fa6f0242a9bdddcfcad1f7e7baf5f4508f95730ccf78bdf97) to include an additional parameter` fileExistsInPath` used to throw an error if the file doesn't exist in path. A check for the same that existed previously is removed in favor of the same performed at an earlier point (proceed with the network call if there isn't a valid file path corresponding to the supplied path/ID). - The test runner is migrated from Jest to Vitest since it supports ESM out of the box. - New e2e test case added with multiple child collections at each level inheriting/overriding authorization and headers set at the parent level, [ref](https://github.com/hoppscotch/hoppscotch/pull/4095/files#diff-5ff84214e6383cbf0d4985dee644ffb5bcf48725d0f6b2339ef3419c103ff549). The existing case included a [fixture](https://github.com/hoppscotch/hoppscotch/blob/53b5808410b9aa97a75dd193efff3248a9d7ced7/packages/hoppscotch-cli/src/__tests__/e2e/fixtures/collections/collection-level-auth-headers-coll.json) (renamed to follow a consistent convention) with deeply nested collections. This new addition ensures the implementation accounts for multiple child collections at each level. - Directory hierarchy updates for the test suite, better separation of concerns with `e2e` tests moved under `__tests__/e2e` and unit tests under `__tests__/unit` with the respective test data maintained under `fixtures` for both directories. The pre-existing unit tests under `__tests__/functions` are to be revisited separately (Tracked in [HFE-326](https://linear.app/hoppscotch/issue/HFE-326/revisit-unit-tests-for-the-cli)) and moved under `__tests__/unit`. Closes HFE-502 HFE-503. ### Steps to verify (SH) - Spin up the `selfhost-web` dev server and the BE container locally. - Obtain a new personal access token to access the workspace resources. It can be done via the UI if checking out to #4094. Alternatively, send a post request to the `http://<localhost_server_url>/v1/access-tokens/create` endpoint with the following body: ```json { "label": "<token-label>", "expiryInDays": 30 } ``` > The above endpoint is behind JWT Auth guards and please ensure to send along the relevant cookies (`access_token`). - Choose a collection to run via the CLI or create one if none exists. - #4141 brings about the support for obtaining the collection/environment ID straightaway from the UI. The CLI command to run a particular collection can be obtained if checking out to the above branch or following the steps below. Grab the collection ID (match the name against the `title` field from the response within the `data.rootCollectionsOfTeam` field and pick the corresponding `id` field value) of interest from the `RootCollectionsOfTeam` GQL query. ```gql query RootCollectionsOfTeam($teamID: ID!, $cursor: ID) { rootCollectionsOfTeam(teamID: $teamID, cursor: $cursor) { id title data } } ``` - Navigate to the `hoppscotch-cli` package path locally and run `pnpm build`. Run the collection via: ```sh bin/hopp.js test <copied_collection-id> --token <access_token> --server <localhost_server_url> ``` > `bin/hopp.js` can be replaced with `hopp` if a symlink is created via [pnpm link](https://pnpm.io/cli/link). > Replace placeholders with the values obtained in the previous steps. `localhost_server_url` defaults to `http://localhost:3170`. - Similarly, if running a collection that requires an environment, grab the environment ID (match the name against the `name` field from the response within the `data.team.teamEnvironments` field and pick the corresponding `id` field value) from the `GetTeamEnvironments` GQL query. ```gql query GetTeamEnvironments($teamID: ID!) { team(teamID: $teamID) { teamEnvironments { id name variables teamID } } } ``` - Run the collection supplying the environment ID: ```sh bin/hopp.js test <copied_collection-id> -e <copied_environment_id> --token <access_token> --server <localhost_server_url> ``` - Both file path and ID can be supplied while specifying an access token. Try out different combinations and the different error scenarios mentioned above. > To verify the changes against the cloud BE, supply `https://stage-api.hoppscotch.io` along with the `--server` flag and obtain the collection/environment IDs from the cloud [staging instance](https://stage.hoppscotch.io/). ### Checks - [x] My pull request adheres to the code style of this project - [x] My code requires changes to the documentation - [ ] I have updated the documentation as required - [x] All the tests have passed ### Note to reviewers E2e additions for the workspace access behavior (tests including the usage of `--token` & `--server` flags) are skipped for now. It'll be enabled once a proper e2e test environment is set up locally. Unit tests are in place for the new functionality added. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>