feat(cli): access team workspace collections and environments

[jamesgeorge007]

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 feat: introduce personal access tokens for authorization #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.

• There'll be a UI flow introduced to obtain the collection ID (and active environment ID) straightaway from the UI within the collection tree. For now, 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:

  hopp <copied_collection-id> --token <access_token> --server <localhost_server_url>
  

  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:

  hopp <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. Hence, try out different combinations and the different error scenarios mentioned above.

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.