This is a template README.md. Be sure to update this with project specific content that describes your ui test project.

UI test suite for the <digital service name> using WebDriver and <scalatest/cucumber>.

Prior to executing the tests ensure you have:

• Docker - to run a Chrome or Firefox browser inside a container
• Appropriate drivers installed - to run tests against locally installed Browser
• Installed MongoDB
• Installed/configured service manager.

Run the following command to start services locally:

sudo mongod
sm --start UI_TEST_TEMPLATE -f

Then execute the run_tests.sh script:

./run_tests.sh <environment> <browser-driver>

The run_tests.sh script defaults to the local environment with the locally installed chrome driver binary. For a complete list of supported param values, see:

• src/test/resources/application.conf for environment
• webdriver-factory for browser-driver

The script ./run-browser-with-docker.sh can be used to start a Chrome or Firefox container on a developer machine. The script requires remote-chrome or remote-firefox as an argument.

Read more about the script's functionality here.

To run against a containerised Chrome browser:

./run-browser-with-docker.sh remote-chrome 
./run_tests.sh local remote-chrome

./run-browser-with-docker.sh is NOT required when running in a CI environment.

To run the tests against an environment set the corresponding host environment property as specified under <env>.host.services in the application.conf.

For example, to execute the run_tests.sh script against QA environment using Chrome remote-webdriver

./run_tests.sh qa remote-chrome

ZAP tests can be automated using the HMRC zap-automation library. It is not mandatory to do so and should not be considered a substitute for manual exploratory testing using OWASP ZAP.

It is not required to proxy every journey test via ZAP. The intention of proxying a test through ZAP is to expose all the relevant pages of an application to ZAP. So tagging a subset of the journey tests or creating a single ZAP focused journey test is sufficient.

Setting the system property zap.proxy=true configures the browser specified in browser property to proxy via ZAP. This is achieved using webdriver-factory.

Running ZAP tests require passing a zap-automation config object to the zap-automation library. zap-automation config is defined in the application.conf. The config is passed to the zap-automation library via ZapSpec from which the ZAP tests are triggered.

The shell script run_zap_tests.sh is available to execute ZAP tests. The script first proxies a set of journey tests, tagged as ZapTests, via ZAP. Upon completion, the script then triggers a ZAP scan for the provided zap-automation config.

For example, to execute ZAP tests locally using a Chrome browser

./run_zap_test.sh local chrome

To execute ZAP tests locally using a Chrome browser

./run-browser-with-docker.sh remote-chrome 
./run_zap_test.sh local remote-chrome

./run-browser-with-docker.sh is NOT required when running in a CI environment.

For more information about ZAP tests, please refer to the zap-automation documentation.

If you would like to run your tests via BrowserStack from your local development environment please refer to the webdriver-factory project.

This project supports UI test execution using Firefox (Geckodriver) and Chrome (Chromedriver) browsers.

See the drivers/ directory for some helpful scripts to do the installation work for you. They should work on both Mac and Linux by running the following command:

./installGeckodriver.sh <operating-system> <driver-version>
or
./installChromedriver <operating-system> <driver-version>

• defaults to linux64, however it also supports macos
• defaults to 0.21.0 for Gecko/Firefox, and the latest release for Chrome. You can, however, however pass any version available at the Geckodriver or Chromedriver repositories.

Note 1: You will need to ensure that you have a recent version of Chrome and/or Firefox installed for the later versions of the drivers to work reliably.

Note 2 These scripts use sudo to set the right permissions on the drivers so you will likely be prompted to enter your password.