From ceea44651b02d24a8639d036e6109005cc2697cf Mon Sep 17 00:00:00 2001 From: Adrienne Bolger Date: Tue, 27 Apr 2021 11:28:06 -0400 Subject: [PATCH] Updating with instructions and local devstack example. --- README.md | 171 --------------------------- README.rst | 186 ++++++++++++++++++++++++++++++ config/admin_portal_devstack.json | 27 +++++ env_vars.env | 21 +++- env_vars_devstack_example.env | 23 ++++ package.json | 4 +- 6 files changed, 256 insertions(+), 176 deletions(-) delete mode 100644 README.md create mode 100644 README.rst create mode 100644 config/admin_portal_devstack.json create mode 100644 env_vars_devstack_example.env diff --git a/README.md b/README.md deleted file mode 100644 index 2fbe04d..0000000 --- a/README.md +++ /dev/null @@ -1,171 +0,0 @@ -# cypress-e2e-tests - -This repo contains e2e tests written in Cypress for different edX applications - ---- ---- - -## Introduction to Cypress - -Cypress is a relatively new automated tests tool which is gaining popularity at a very rapid pace - -Here is the home page for Cypress if someone wants to look it up - - - -Cypress has very strong documentation so a new comer could find most of the information from their own site - - - -Also as a starting point it would be good to go through these tutorial videos - - - ---- ---- - -## E2E Tests Repo - -This repo is meant to contain multiple projects, for now there is one project: - -Enterprise Admin Portals (Active) - -With time we will add more projects in the repo - ---- ---- - -## Protocols for Test Design - -We don't yet have well defined protocols for writing Cypress tests for edX application, so this work was mostly experimental - -The first project was MIT Journals (which has since been deprecated and removed). - -In the second project, Enterprise Admin Portal, the following approach was used: - -* Page Object model is used in spite of what Cypress site says, it increases readability of code and is much easier to manage - -* Instead of using arrow functions traditional named functions are used, this is done to to be able to use **this**, which is not working with arrow functions - -* Cypress commands and helper functions are still utilized - -The tests for Enterprise Admin Portal are present in following path - - - -To manage multiple projects customized config files are used so user is able to run any project without making any change in the code - -Config files for projects are placed here - - - ---- ---- - -## Test Setup - -### Installations - -You need to have Node.js installed before using Cypress. - -For rest of the installations move to project folder in command prompt and type - -`npm install` - -which will install Cypress and other supporting tools - ---- - -### Environment Variables - -Following Environment Vars should be set before running the tests - -`CYPRESS_LMS_USER_EMAIL` - -`CYPRESS_LMS_USER_PASSWORD` - -_Note_: The above are credentials for a normal edX user who does not have access to admin portal - -`CYPRESS_ADMIN_USER_EMAIL` - -`CYPRESS_ADMIN_USER_PASSWORD` - -_Note_: The above are credentials for an admin portal valid user - -Following environment vars would be required for using google api to read gmail inbox - -`CYPRESS_GMAIL_ID` - -`CYPRESS_GMAIL_CLIENT_ID` - -`CYPRESS_GMAIL_CLIENT_SECRET` - -`CYPRESS_GMAIL_ACCESS_TOKEN` - -`CYPRESS_GMAIL_REFRESH_TOKEN` - -_Note_: You can use the method descibed in the below link to get these auth tokens for any personal gmail account - - - ---- - -### Run Tests - -To run admin portal tests in interactive mode use following command - -`npm run cy:open_admin_portal` - -To run admin portal tests in normal mode use following command - -`npm run cy:run_admin_portal` - ---- - -### Using ES LInt - -ESLint is also setup in the repo, you can use it by typing following command in terminal - -`npm run lint` - ---- - -## Docker Setup - -Docker setup is also available for those who want to run the tests without doing any installations - -To run the tests in Docker - -* Provide the values for environment variables in the env_vars.env -* Use following command in terminal - `docker-compose -f docker-compose.yml -f cy-run.yml up` - ---- - -## Running Tests in Interactive Mode using Docker - -You can also execute tests in interactive mode directly from Docker, for that you would need to do -some extra steps - -As a pre-requisite you need to install XQuartz using following command - -`brew cask install xquartz` - -or install it directly from - -### To configure XQuartz - -* Open XQuartz using following command in terminal - * `open -a XQuartz` -* In the XQuartz preferences, go to the “Security” tab and make sure you’ve got “Allow connections from network clients” ticked - -### To run the tests - -* Provide the values for environment variables in the env_vars.env -* Grab the IP of the host machine and add it to the allowed X11 hosts by running these commands - * `IP=$(ipconfig getifaddr en0)` - * `/usr/X11/bin/xhost + $IP` -* Pass the environment variable DISPLAY to show Cypress GUI on the host system - * `DISPLAY=$IP:0` -* Use following command in terminal - * `docker-compose -f docker-compose.yml -f cy-open.yml up` diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..00592f7 --- /dev/null +++ b/README.rst @@ -0,0 +1,186 @@ +***************** +cypress-e2e-tests +***************** + +This repo contains e2e tests written in Cypress for different edX applications + +======================= +Introduction to Cypress +======================= + +Cypress is a relatively new automated tests tool which is gaining popularity at a very rapid pace. (https://www.cypress.io) + +Cypress newcomer tutorial: https://docs.cypress.io/guides/overview/why-cypress.html#In-a-nutshell + +Starting tutorial videos: https://docs.cypress.io/examples/examples/tutorials.html#Best-Practices + +============== +E2E Tests Repo +install============== + +This repo is meant to contain multiple projects. For now there are 2 projects: + +Enterprise Admin Portals (Active) + +Authentication MFE + +With time we will add more projects in the repo + +========================= +Protocols for Test Design +========================= + +We don't yet have well defined protocols for writing Cypress tests for edX application, so this work is still experimental + +The first project was MIT Journals (which has since been deprecated and removed). + +In the second project, Enterprise Admin Portal, the following approach was used originally: + +* Page Object model is used in spite of what Cypress site says, it increases readability of code and is much easier to manage +* Instead of using arrow functions traditional named functions were used, this is done to to be able to use **this**, which is not working with arrow functions + +THIS IS UNDER DEVELOPMENT AND BEING REPLACED WITH BEST PRACTICES THAT USE MODERN JAVASCRIPT. +ALL FUTURE ADMIN PORTAL TESTS SHUOLD BE CODE REVIEWED AGAINST THE FOLLOWING GUIDELINES IN MIND: +https://docs.cypress.io/guides/references/best-practices + +* Cypress commands and helper functions are still utilized + +The tests for Enterprise Admin Portal are present in following path + +https://github.com/edx/cypress-e2e-tests/tree/master/cypress/integration/admin_portal + +To manage multiple projects customized config files are used so user is able to run any project without making any change in the code + +Config files for projects are placed here + +https://github.com/edx/cypress-e2e-tests/tree/master/config + + +=================== +Configuration Setup +=================== + +1. Fill in your desired Environment Variable values in `env_vars.env`. +Example config for use with the devstack-provisioned data can be found in the file env_vars_devstack_example.env, but enterprise_id and enterprise_catalog are generated at provision time, so you'll need to replace those with your local instance. Note also that "localhost" will not work if Cypress is called from inside a docker container, so if you are using Devstack+docker, you will need to replace localhost in environment variable URLs with the local ip (see section on Docker+Devstack). + + + +2. The following additional environment vars are required for using google api to read gmail inbox + + `CYPRESS_GMAIL_ID` + + `CYPRESS_GMAIL_CLIENT_ID` + + `CYPRESS_GMAIL_CLIENT_SECRET` + + `CYPRESS_GMAIL_ACCESS_TOKEN` + + `CYPRESS_GMAIL_REFRESH_TOKEN` + +You can use the method described in the below link to get these auth tokens for any PERSONAL gmail account +(Note: if you are an edX employee, you will NOT be able to use your edX gmail for this without filing an IT ticket, as edX locks down the Google Console.) + +https://developers.google.com/identity/protocols/OAuth2WebServer#creatingcred + + +=========================== +Setup and Run Tests locally +=========================== + +You need to have Node.js and a n installed before using Cypress. + +From the repository root folder: + +`npm install` + +Source and export your configured environment file variables into your local shell for Cypress to find: + +`source env_vars.env` + +`export $(cut -d= -f1 env_vars.env)` + +To run admin portal tests in interactive mode against edX Staging, use following command + +`npm run cy:open_admin_portal` + +To run Enterprise Admin portal tests in normal mode against edX Staging, use following command + +`npm run cy:run_admin_portal` + +To run Enterprise Admin portal tests against your local Devstack setup, use the following commands: + +`npm run cy:open_admin_portal_devstack` + +`npm run cy:run_admin_portal_devstack` + + +============================================= +Setup and Run Tests in Normal mode via Docker +============================================= + +Docker setup is also available for those who want to run the tests without installing +node locally: + +1. Provide the values for environment variables in the env_vars.env + +2. To run tests against edX.org STAGING, use following command in terminal: + + `docker-compose -f docker-compose.yml -f cy-run.yml up` + +3. Note that if you modify any environment variables you will need to rebuild your container with the `--build` flag to see the changes: + + Example: `docker-compose -f docker-compose.yml -f cy-run.yml up --build` + +==================================================== +Setup and Run Tests in Interactive Mode via Docker +==================================================== + +(Note: these instructions have only been tested on a Mac) + +Executing tests in interactive mode from Docker requires the following extra steps: + +1. As a pre-requisite you need to install XQuartz on your host machine. If you are on a Mac, you can use brew. XQuartz is also installable from + + `brew install --cask xquartz` + +2. (Steps from here down must be performed for each run) Once installed, open XQuartz using following command in terminal and leave it running for the length of your tests. + + `open -a XQuartz` + +3. In the XQuartz preferences, go to the “Security” tab and make sure you’ve got “Allow connections from network clients” ticked + +4. Ensure you have finished the Configuration Setup step by +providing the values for environment variables in the env_vars.env. If you are running devstack on your host machine, you will need to use host IP address in env_vars.env. + +5. Once you have XQuartz running (see step 3), locate the IP of your host machine and add it to the allowed X11 hosts by running these commands: + + `IP=$(ipconfig getifaddr en0)` + + `export IP` + + `/usr/X11/bin/xhost + $IP` + + Expected output should look something like `localhost being added to access control list` + +6. Pass the environment variable DISPLAY to show Cypress GUI on the host system by running the following command: + + `export DISPLAY=$IP:0` + +7. Bring up your docker container: + + For edX Staging configuration: + + `docker-compose -f docker-compose.yml -f cy-open.yml up` + +8. Note that if you modify any environment variables you will need to rebuild your container with the `--build` flag to see the changes: + + Example: `docker-compose -f docker-compose.yml -f cy-open.yml up --build` + +============= +Using ES LInt +============= + +ESLint is also setup in the repo, you can use it by typing following command in terminal + +`npm run lint` + diff --git a/config/admin_portal_devstack.json b/config/admin_portal_devstack.json new file mode 100644 index 0000000..c1bd597 --- /dev/null +++ b/config/admin_portal_devstack.json @@ -0,0 +1,27 @@ +{ + "integrationFolder": "cypress/integration/admin_portal/tests", + "fixturesFolder": "cypress/fixtures/admin_portal", + "defaultCommandTimeout": 10000, + "requestTimeout": 10000, + "pageLoadTimeout": 80000, + "taskTimeout": 300000, + "chromeWebSecurity": false, + "projectId": "3se7u6", + "blockHosts": [ + "**.cdn.**", + "cdn.*", + "*.optimizely.**", + "www.googletagmanager.com", + "www.google-analytics.com", + "*.qualaroo.**", + "s3.amazonaws.com", + "bam.nr-data.net**" + ], + "env": { + "ENVIRONMENT": "enterprise_devstack_config" + }, + "retries": { + "runMode": 2, + "openMode": 2 + } +} \ No newline at end of file diff --git a/env_vars.env b/env_vars.env index b656f69..427d6b0 100644 --- a/env_vars.env +++ b/env_vars.env @@ -1,8 +1,21 @@ # provide environment variables for docker here -CYPRESS_LMS_USER_EMAIL={} -CYPRESS_LMS_USER_PASSWORD={} -CYPRESS_ADMIN_USER_EMAIL={} -CYPRESS_ADMIN_USER_PASSWORD={} +CYPRESS_LMS_USER_EMAIL=enterprise_learner@example.com +CYPRESS_LMS_USER_PASSWORD=edx +CYPRESS_ADMIN_USER_EMAIL=enterprise_admin@example.com +CYPRESS_ADMIN_USER_PASSWORD=edx + +CYPRESS_lms_url="http://localhost:18000" +CYPRESS_login_url="http://localhost:18000/login" +CYPRESS_login_api_url="http://localhost:18000/user_api/v1/account/login_session/" +CYPRESS_ecommerce_url="http://localhost:18130" +CYPRESS_baseUrl=http://localhost:1991 + + +CYPRESS_enterprise_name="Test Enterprise" +CYPRESS_enterprise_slug="test-enterprise" +CYPRESS_enterprise_id=e40e0ece-ccc6-41b6-9c51-750f84d56d8f +CYPRESS_enterprise_catalog=70043ca2-87b6-4dcc-b8b8-e66495a373ce + CYPRESS_GMAIL_ID={} CYPRESS_GMAIL_CLIENT_ID={} CYPRESS_GMAIL_CLIENT_SECRET={} diff --git a/env_vars_devstack_example.env b/env_vars_devstack_example.env new file mode 100644 index 0000000..427d6b0 --- /dev/null +++ b/env_vars_devstack_example.env @@ -0,0 +1,23 @@ +# provide environment variables for docker here +CYPRESS_LMS_USER_EMAIL=enterprise_learner@example.com +CYPRESS_LMS_USER_PASSWORD=edx +CYPRESS_ADMIN_USER_EMAIL=enterprise_admin@example.com +CYPRESS_ADMIN_USER_PASSWORD=edx + +CYPRESS_lms_url="http://localhost:18000" +CYPRESS_login_url="http://localhost:18000/login" +CYPRESS_login_api_url="http://localhost:18000/user_api/v1/account/login_session/" +CYPRESS_ecommerce_url="http://localhost:18130" +CYPRESS_baseUrl=http://localhost:1991 + + +CYPRESS_enterprise_name="Test Enterprise" +CYPRESS_enterprise_slug="test-enterprise" +CYPRESS_enterprise_id=e40e0ece-ccc6-41b6-9c51-750f84d56d8f +CYPRESS_enterprise_catalog=70043ca2-87b6-4dcc-b8b8-e66495a373ce + +CYPRESS_GMAIL_ID={} +CYPRESS_GMAIL_CLIENT_ID={} +CYPRESS_GMAIL_CLIENT_SECRET={} +CYPRESS_GMAIL_ACCESS_TOKEN={} +CYPRESS_GMAIL_REFRESH_TOKEN={} \ No newline at end of file diff --git a/package.json b/package.json index b6a0746..487ab1f 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,8 @@ "cy:run_admin_portal": "cypress run --env ENVIRONMENT=admin_portal_stage", "cy:open_authn_mfe": "cypress open --env ENVIRONMENT=authn_mfe_stage", "cy:run_authn_mfe": "cypress run --env ENVIRONMENT=authn_mfe_stage", + "cy:open_admin_portal_devstack": "cypress open --env ENVIRONMENT=admin_portal_devstack", + "cy:run_admin_portal_devstack": "cypress run --env ENVIRONMENT=admin_portal_devstack", "lint": "eslint --ext .js --ext .jsx .", "lint:fix": "eslint --ext .js --ext .jsx . --fix", "precommit": "npm run lint" @@ -24,4 +26,4 @@ "googleapis": "42.0.0", "uuid": "^3.3.2" } -} +} \ No newline at end of file