akkeris/ui repository overview

⁠Akkeris UI

• Akkeris UI⁠
  • Setup⁠
  • Environment⁠
    • Authentication⁠
    • Session⁠
    • Akkeris Specific⁠
  • Testing⁠
    • Automated Test Runner⁠
      • Environment⁠
      • Run⁠
    • Selenium⁠
      • Environment⁠
      • Run⁠
    • Docker Image⁠
      • Environment⁠
      • Run⁠
    • Manually via Testcafe⁠
    • Taking Screenshots⁠

⁠Setup

---

To run locally,

1. Add application authorization to your oauth
2. Add application with redirect of http://localhost:3000/oauth/callback
3. Save id and secret as environment variables
4. start redis in brew

   brew install redis
   brew services start redis
   

   Copy
5. run

   npm install
   npm start
   

   Copy

⁠Environment

---

⁠Authentication

Connect an oauth provider with the following env info.

• CLIENT_ID
• CLIENT_SECRET
• OAUTH_ENDPOINT (In the format schema://host no path is necessary, e.g., no /authorize etc.)

We also connect to github for use of repo webhooks. Register this app with your account or organization like explained here⁠.

• GIT_CLIENT_ID
• GIT_CLIENT_SECRET

⁠Session

We use a redis cache for session storage. Create an encryption secret and add it to the env.

• REDIS_URL (defaults to localhost, can be Akkeris)
• SESSION_SECRET

⁠Akkeris Specific

• CLIENT_URI (defaults to localhost)
• AKKERIS_API (backend api server)

⁠Testing

Testing is provided via a series of Testcafe scripts in the test/e2e directory. A few different methods have been provided to run these tests:

• Automated Test Runner⁠ (recommended)
• Docker Image⁠
• Selenium⁠
• Manually via Testcafe⁠

If you're not sure which option to choose, start with the Automated Test Runner option.

Please note that for these tests the UI must be running somewhere (e.g. on your local machine) and be accessible to the test driver.

⁠Automated Test Runner

If you have Chrome (or Firefox) installed on your local machine, you can set some environment variables and have npm automatically run Testcafe tests with the same npm start command used for starting the UI.

You can also use this option to automatically "clean up" remaining Akkeris resources if tests fail by providing the AKKERIS_API and OAUTH_ENDPOINT options.

This is the preferred (and easiest) option for testing on development machines

⁠Environment

For screenshot options, see the Taking Screenshots⁠ section below.

⁠Run

Given that the applicable environment variables have been saved to config.env...

1. source config.env
2. npm start

The presence of the "RUN_TESTCAFE" environment variable will instruct the UI to run the Testcafe tests rather than starting normally.

⁠Selenium

If you have access to Selenium Grid (open source and simple to setup⁠), you can run Testcafe tests using Selenium as a remote browser. This is especially useful for testing with Akkeris TaaS⁠.

This method utilizes the Automated Test Runner⁠.

⁠Environment

For screenshot options, see the Taking Screenshots⁠ section below.

⁠Run

With Docker:

Given that the applicable environment variables have been saved to config.env...

1. docker build -t akkeris-ui .
2. docker run --env-file config.env -n akkeris-ui --rm akkeris-ui

Locally:

1. source config.env
2. npm start

⁠Docker Image

A Dockerfile has been provided in the test directory for running Testcafe tests entirely in Docker. It contains both Chromium and Firefox along with XVFB, Fluxbox, and all the bits and pieces needed to virtualize browsers and test code in Docker. This image is built upon the Testcafe docker image⁠.

This method isn't recommended as it requires building a seperate Docker image and uses quite a bit of resources, but is provided just in case. Please note that this method isn't officially supported and functionality may be unstable.

⁠Environment

⁠Run

Given that the applicable environment variables have been saved to config.env...

1. cd test
2. docker build -t akkeris-ui-tests .
3. docker run --env-file config.env --name akkeris-ui-tests --rm akkeris-ui-tests

Note - the docker image does not use the RUN_TESTCAFE environment variable because it does not contain the full UI.

⁠Manually via Testcafe

You can also access Testcafe directly, if desired. The following environment variables are required for manually running tests:

• BASE_URL
• OAUTH_ENDPOINT
• BOT_USER
• BOT_PASS

(see the above section for an explanation of these variables)

Once these variables are set, you can then access Testcafe directly:

• npm run testcafe - Run all Testcafe tests with the "chrome:headless" browser.

OR to run specific tests...

• npm install - Make sure Testcafe is installed
• ./node_modules/.bin/testcafe [BROWSER] [TEST TO RUN] e.g. ./node_modules/.bin/testcafe chrome test/e2e/apps.test.js

For more information on the available Testcafe CLI options, see the Testcafe documentation⁠).

⁠Taking Screenshots

Screenshot configuration via environment variables are available using the Automated Test Runner⁠ or Selenium⁠ testing methods.

If you want Testcafe to take screenshots when a test fails and upload them to S3, set the following environment variables: