This test suite tests the Boundary Admin UI in an end-to-end setting. It was designed to be run in a variety of environments as long as the appropriate environment variables are set. You can choose to spin up your own infrastructure or use Enos to generate it for you. More information about Enos available here.

The test suite uses the Playwright framework.

Prerequisites:

You will need Homebrew install. For secure persisting your SSH keys and tokens we recommend using 1Password.

Accesses

If you are missing any acccess, requested through the IT service catalog.

Doormat account: boundary_team_acctest_dev.
HCP account: you will need to use Terraform cloud to spin up enos.

Software

Vault: documentation how to install.
Terraform: documentation how to install.
Github CLI: documentation how to install.
Install Enos: documentation how to install using homebrew, also binaries available here.
Install Doormat CLI: documentation how to install.
Install AWS CLI (Optional): documentation how to install.

Getting Started

We will cover everything you need to set up before being able to run Enos + the tests.

Set up Boundary CLI

Ensure the boundary CLI is available on the path. You can validate this by making sure this command returns something.

which boundary

Otherwise, follow instructions to install Boundary or install it locally running $ make install within Boundary repository.

Setup Boundary UI

Ensure you install project dependencies and playwright needs.

cd boundary-ui/ui/admin
yarn install
npx playwright install # this installs the browsers used by Playwright

Setup AWS:

Region awareness: take note of the AWS region you are setting up because we will need it later to configure enos. More information about AWS regions.

SSH Key pair:

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.

How to create EC2 SSH key pair.

Setup HCP Terraform (Terraform cloud):

Log in to HCP Production env. Through HCP Terraform, open Terraform cloud, or access here. Then create an API token following this documentation.

Token awareness: Copy your token from the box and save it in a secure location. Terraform Cloud only displays the token once, right after you create it. And we will need the token later for enos configuration.

Setup Enos:

Enos needs some configuration variables to run the scenario successfully. See the configuration file. The file has comments per each variable, but some awareness:

aws_region: The AWS region you are using. Very important as mentioned within the EC2 Setup.
aws_ssh_keypair_name: The name of the AWS keypair.
aws_ssh_private_key_path: The path to the private key associated with your keypair.
enos_user: The user name to use for Boundary.
tfc_api_token: you need to provide the previously created token in Terraform cloud, there is no shared token within Boundary team.
local_boundary_dir: The directory that contains Boundary binary.
local_boundary_ui_dir: The directory that contains the copy of boundary-ui you want to use for UI tests.
e2e_debug_no_run: make sure this is set to true.

More documentation about scenario variables.

Run tests:

Before running the e2e test locally, we need to launch Enos Scenario, make sure you followed all the steps within the Getting started section.

It is not necessary, but from this point we recommend having 2 terminals open.

Terminal 1: Will be use to run enos (Boundary).
Terminal 2: Will be use to run e2e UI tests (Boundary UI).

Launch Enos Scenario

Using Terminal 1:

$ cd boundary/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 builder:local. Launch enos scenario, this will take from 5 to 10 minutes. When its done, you will see a Enos Operations finished! within your terminal.
$ 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 need within Boundary UI to run the test against the enos scenario.

Be aware once the scenario is launch you will create and run resources within AWS, once you are done using the scenario, you should destroy it.

Run tests

Using Terminal 2:

Set the env varibales test_e2e_env.sh script output within this terminal.
$ cd boundary-ui/ui/admin.
$ yarn run e2e.

Here are some additional commands to assist with debugging.

PWDEBUG=console yarn playwright test --headed --config ./tests/e2e/playwright.config.js login.spec.js
PWDEBUG=console yarn playwright test --headed --config ./tests/e2e/playwright.config.js login.spec.js:13 --debug
PWDEBUG=console yarn playwright test --headed --config ./tests/e2e/playwright.config.js login.spec.js --debug

To run the tests with a specific tag (e.g. @enterprise), use this command.

PWDEBUG=console yarn playwright test --grep @enterprise --headed --config ./tests/e2e/playwright.config.js delete-resources.spec.js

To run all tests except those with a specific tag (e.g. @enterprise), use this command.

PWDEBUG=console yarn playwright test --grep-invert @enterprise --headed --config ./tests/e2e/playwright.config.js delete-resources.spec.js

Playwright documentation about running tests.

Destroy Enos Scenario

Using Terminal 1:

$ enos scenario destroy e2e_ui builder:local
After all the steps pass, you should see a Enos operations finished!.

Developing Tests

It is recommended to use locators that resemble how users interact with the application. getByRole should be the most prioritized locator as this is the closest way to how users and accessibility features perceive the page. getByLabel should be used for form fields.

Additional information can be found here and here.