From a2cc33d405f006a128fc0649e58d7ffc81f15651 Mon Sep 17 00:00:00 2001 From: Carlos Alcaide Corvo Date: Fri, 19 May 2023 16:10:55 -0700 Subject: [PATCH] e2e Test documentation for FE onboarding (#1681) * Add e2e documentation to faciltiate FE devs onboarding Co-authored-by: Michael Li Co-authored-by: lisbet-alvarez <107949262+lisbet-alvarez@users.noreply.github.com> --------- Co-authored-by: Michael Li Co-authored-by: lisbet-alvarez <107949262+lisbet-alvarez@users.noreply.github.com> --- ui/admin/package.json | 2 +- ui/admin/tests/e2e/README.md | 135 +++++++++++++++++++++++++++++++---- 2 files changed, 122 insertions(+), 15 deletions(-) diff --git a/ui/admin/package.json b/ui/admin/package.json index 137d535d9..1e7f567d6 100644 --- a/ui/admin/package.json +++ b/ui/admin/package.json @@ -10,7 +10,7 @@ "test": "tests" }, "scripts": { - "doc:toc": "doctoc README.md", + "doc:toc": "doctoc README.md tests/e2e/README.md", "build:development": "ember build", "build": "ember build --environment=production", "build:oss": "EDITION=oss ember build --environment=production", diff --git a/ui/admin/tests/e2e/README.md b/ui/admin/tests/e2e/README.md index 9560a2109..e6de7407c 100644 --- a/ui/admin/tests/e2e/README.md +++ b/ui/admin/tests/e2e/README.md @@ -1,19 +1,59 @@ + + + +# Admin UI e2e tests + +- [Admin UI e2e tests](#admin-ui-e2e-tests) + - [Prerequisites:](#prerequisites) + - [Accesses](#accesses) + - [Software](#software) + - [Getting Started](#getting-started) + - [Set up Boundary CLI](#set-up-boundary-cli) + - [Setup Boundary UI](#setup-boundary-ui) + - [Setup AWS:](#setup-aws) + - [Setup HCP Terraform (Terraform cloud):](#setup-hcp-terraform-terraform-cloud) + - [Setup Enos:](#setup-enos) + - [Run tests:](#run-tests) + - [Launch Enos Scenario](#launch-enos-scenario) + - [Run tests](#run-tests) + - [Destroy Enos Scenario](#destroy-enos-scenario) + - [Developing Tests](#developing-tests) + + # Admin UI e2e tests 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](https://github.com/hashicorp/boundary/tree/main/enos) -to generate it for you. +to generate it for you. More information about [Enos available here.](https://github.com/hashicorp/Enos-Docs) The test suite uses the [Playwright](https://playwright.dev/) framework. +## Prerequisites: + +You will need [Homebrew](https://brew.sh/) 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](https://hashicorp.freshservice.com/support/catalog/items). + +- 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](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). + ## Getting Started -Setup... -```bash -cd boundary-ui/ui/admin -yarn install -npx playwright install # this installs the browsers used by Playwright -``` + +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. @@ -21,16 +61,73 @@ command returns something. which boundary ``` -Run tests... +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). + +### Setup Boundary UI + +Ensure you install project dependencies and playwright needs. + ```bash -export BOUNDARY_ADDR= -export E2E_PASSWORD_ADMIN_LOGIN_NAME= -export E2E_PASSWORD_ADMIN_PASSWORD= -export E2E_PASSWORD_AUTH_METHOD_ID= -... # Tests may have additional variables that it needs cd boundary-ui/ui/admin -yarn run e2e +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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). + +**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](https://docs.aws.amazon.com/ground-station/latest/ug/create-ec2-ssh-key-pair.html). + +### Setup HCP Terraform (Terraform cloud): + +Log in to [HCP Production env](https://portal.cloud.hashicorp.com/). Through HCP Terraform, open Terraform cloud, or [access here](https://app.terraform.io/). Then create an API token [following this documentation](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/users#tokens). + +**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](https://github.com/hashicorp/boundary/blob/main/enos/enos.vars.hcl). 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](https://github.com/hashicorp/boundary/tree/main/enos#scenarios-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](#getting-started). + +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](#destroy-enos-scenario).* + +### 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. ```bash @@ -39,6 +136,16 @@ PWDEBUG=console yarn playwright test --headed --config ./tests/e2e/playwright.co PWDEBUG=console yarn playwright test --headed --config ./tests/e2e/playwright.config.js login.spec.js --debug ``` +[Playwright documentation about running tests](https://playwright.dev/docs/running-tests). + +### Destroy Enos Scenario + +Using Terminal 1: +- `$ enos scenario destroy`. +- 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`