- Vault: [documentation how to install](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-install).
- Terraform: [documentation how to install](https://developer.hashicorp.com/terraform/downloads).
- Github CLI: [documentation how to install](https://cli.github.com/manual/installation).
- Install Enos: [documentation how to install using homebrew](https://github.com/hashicorp/Enos-Docs/blob/main/installation.md), also binaries available [here](https://github.com/hashicorp/enos/releases).
- Install Doormat CLI: [documentation how to install](https://docs.prod.secops.hashicorp.services/doormat/cli/).
- Install AWS CLI (Optional): [documentation how to install](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Otherwise, follow instructions to [install Boundary](https://developer.hashicorp.com/boundary/downloads?product_intent=boundary) or install it locally running `make install` within [Boundary repository](https://github.com/hashicorp/boundary/tree/main).
**Region awareness:** take note of the AWS region you are setting up because we will need it later to configure enos. We recommend `us-east-1`. [More information about AWS regions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).
You need to provide an SSH Key pair for the EC2 instance. We recommend creating specific e2e SSH keys and not re-use existing ones. To differentiate them, we recommend adding `enos` to the name, i.e: `name_enos`.
# Feel free to use a custom name for your key pair if you don't want to use $USER, just make sure it follows the <name>_enos format so it can be identified. e.g. zed_enos
Enos needs some configuration variables to run the scenario successfully. [See the configuration file](https://github.com/hashicorp/boundary/blob/main/enos/enos.vars.hcl). The file has comments per each variable, but some awareness:
Before running e2e tests locally, we need to launch the correct Enos Scenario.
#### Admin
Tests names are tagged (eg: `@docker`) to show which enos scenarios are supported. Some tests will support multiple tags while others require a specific enos scenario in order to run successfully. Put another way, not all tests will run successfully under all enos scenarios. Either check the test name and its corresponding tags or use the `--list` flag for any playwright command to output tests covered:
Currently the desktop client e2e tests assumes using an enterprise enos scenario, either: `e2e_ui_aws_ent` (with aws) or `e2e_ui_docker_ent` (with docker)
-`cd boundary/enos` or `cd boundary_enterprise/enos`.
-`doormat login`. Login with Doormat.
-`eval "$(doormat aws export --account boundary_team_acctest_dev)"`. Exporting AWS env variables from doormat to your terminal.
-`enos scenario launch e2e_ui_aws builder:local` or `enos scenario launch e2e_ui_aws_ent builder:local` if in enterprise.
- Launches enos scenario, this will take from 5 to 10 minutes. When its done, you will see a Enos Operations finished! within your terminal. Check out more scenarios [here](https://github.com/hashicorp/boundary/tree/main/enos).
-`bash scripts/test_e2e_env.sh`. Prints all the env variables within Enos scenario. Copy the output and paste it within your Terminal 2 (Boundary UI). These env variables are needed within Boundary UI to run the test against the enos scenario.
Alternatively, you can also redirect the output to an `.env` file that will get picked up by tests automatically which is useful if you're running tests in your IDE:
> Be aware that once an aws scenario is launched you will create and run resources within AWS. After you are done using the scenario, [you should destroy it](#destroy-enos-scenario). This isn't necessary but still a good idea for docker enos scenarios.
For admin tests, it's important to tag the test with the correct tags to denote which enos scenario is supported by the test. The test tags should have at least specifying the edition (`@ce`, `@ent`) and at least one specifying the enos test infrastructure (`@aws`, or `@docker`).
The `@ent` and `@ce` tags should be added to *all* and *any* test cases that are supported by the respective editions. If a test case can be ran in both editions it should have both tags.
The `apiClient` fixture is available in tests to make calls against the boundary api. This fixture wraps an api client that is auto-generated from the [boundary api openapi swagger spec](https://raw.githubusercontent.com/hashicorp/boundary/main/internal/gen/controller.swagger.json).
#### Using the fixture
The api client fixture can be used in tests anywhere fixtures are available:
* The api client should have all publicly documented APIs
* Generated api client uses typescript to help with the discovery of the required arguments
* Any untyped `attributes` that have been documented by a `description` in the swagger doc will also be included as a docblock comment when inspecting `attributes` in the editor (see `ControllerApiResourcesAccountsV1Account.attributes` in `models/ControllerApiResourcesAccountsV1Account.ts` for an example)
* Automatic resource clean up
* Any resources created by the api client will be automatically cleaned up after the test is finished. To skip cleanup of a resource pass in the created resource to `apiClient.skipCleanup(createdResource);` (where `createdResource` has an `id` property).
* In some cases resources will need child resources, created outside the api, to be cleaned up first. For example, a storage bucket created by the api client cannot be automatically cleaned up until all session recordings have been deleted. Session recordings are created automatically and not tracked by the API so these need to be deleted manually. Session recordings cannot be deleted unless they are in a `available` state which depends on the session being recorded being in a `terminated` state. Sessions also are not created by the api and need to be cleaned up manually.
* Error logging
* When api calls fail with an http status code >= 400 the error response is logged
#### Generating the api client
The generated client is found in the `api-client` folder. Manual changes should not be made to any of the files in this folder because they will be overriden the next time the client is generated.
To regenerate the api-client run the `generate:api` package.json scripts command. By default this will use the latest swagger doc from the public [`boundary` repo](https://github.com/hashicorp/boundary) on the `main` branch at `main/internal/gen/controller.swagger.json`. Note: The `generate:api` script calls `openapi-generator-cli` which requires java to be available on your PATH environment variable.
```shell
pnpm generate:api-client
```
If working on an E2E test that is working against a different version of the boundary api, ensure the updated openapi swagger doc has been generated and set `OPENAPI_SWAGGER_URL_OR_FILE` to the path or url:
```shell
# using a custom url (must be publicly accessible)
# in the following example $COMMITISH can be replaced with a branch name, commit, or tag
Consider committing any changes to the generated `api-client` directory if the changes are needed for the current e2e tests to pass.
### Testing with resources (api, page objects, cli)
When testing an E2E workflow, resources often use page objects (within `admin/pages` and `desktop/pages`) or use methods on playwright locators directly. These simulate user actions to ensure that we are testing our applications the way our users use them.
In cases where resources need to be scaffolded as a prerequisite to a test, but are not needed to be tested directly, the `apiClient` fixture should be used. This type of common setup can usually be done in `test.beforeEach` to separate it from the `test` itself. Using the `apiClient` has the added benefit of:
* being quicker to set up (api calls are faster)
* return api responses and resource definitions
* any created resource is automatically cleaned up after the test
Aside from creating resources, the `apiClient` fixture can be used in any case where interaction with the boundary api is needed.
As a last resort when page objects and the `apiClient` fixture can't be used then the boundary cli helper can be used.
