Running Nightwatch tests in Acquia Code Studio
- Last updated
- 1 minute read
Goal
Learn how to run Nightwatch tests to test your Drupal application on Acquia Code Studio.
Overview
Nightwatch is an automated testing framework for web applications and websites. It uses the W3C WebDriver API to simulate real user interactions in a web browser environment, such as Chrome, to test the complete flow of an application, end-to-end.
In this tutorial, we'll see how we can extend the Acquia AutoDevOps template that comes out-of-the-box with Code Studio to also run Nightwatch tests for our application so we can ensure critical features remain functional as we further develop and maintain it.
-
A simple Nightwatch test
To start, let's first add a simple Nightwatch test to verify Drupal is up and running by navigating to the Drupal login page and checking to see if the expected fields are present. If you already have Nightwatch tests for your application, you can go ahead and skip to the next step.
At the root of our project, we will create the directories "tests/src/Nightwatch/Tests" and "tests/src/Nightwatch/Commands". For the purposes of this tutorial, we will only be using the first one to hold our simple test that checks whether we can access Drupal's login screen. In the other, you can put any custom Nightwatch commands you may have that help with running your tests.
So, once we have our tests directory, let's go ahead and create a file called "checkDrupalLoginScreen.js" and add the following inside:
Make note of the tag "myproject" we added to our test as we will use it later to run it.
-
Extend the Acquia AutoDevOps template
Navigate to your project page on https://code.acquia.com and do the following:
- On the left hand sidebar, find and click Settings > CI/CD.
- At the top of the page there should be a "General pipelines" section. Click Expand.
- In the fields that show up you will see one called "CI/CD configuration file", which should be pre-filled with the path to the Acquia AutoDevOps template. Make note of the template path in case you need to restore it later (in case you haven't, it's "gitlab-ci/Auto-DevOps.acquia.gitlab-ci.yml@acquia/standard-template").
- Delete the Acquia template entry and either:
- Leave it empty. This will pick up the .gitlab-ci.yml file from the root directory of our project (this is what we will do for our purposes here).
- Add a path to the directory where you want to store your .gitlab-ci file relative to the root of the code repository (e.g. my/path/.gitlab-ci.yml).
- In our project's root directory, we will now go ahead and create our .gitlab-ci.yml file.
At the top of our .gitlab-ci.yml file we will add:
Using include, Gitlab allows us to include external YAML files into our own CI file. In our case, we are including the same file we removed from the Code Studio UI earlier. This allows us to use the predefined pipeline configuration in our project while also extending it to add our own pieces, such as a step for running Nightwatch tests.
-
Variables
Next we will define variables for our project's pipeline.
It is important to note here that Acquia recommends adding variables through the Code Studio UI. Variables added through the Code Studio UI take higher precedence than variables defined in the .gitlab-ci.yml file. As such, if we have a variable defined in both places, the one added through the Code Studio UI will take effect, which may lead to unexpected results.
For the purposes of this tutorial, we will add our variables in our .gitlab-ci.yml while making sure we are not overriding those same variables in the Code Studio UI.
The Acquia variables are included here for completeness of the example and are not mandatory. They can also be configured via the Code Studio UI.
-
Nightwatch
Once we've extended the Acquia AutoDevOps template and defined our variables, it's time to add our Nightwatch step.
We want Nightwatch to execute as part of the "Test Drupal" stage that Code Studio already executes as part of the standard pipeline.
We will use the mysql service because we want to be able to install Drupal using MySQL (alternatively you can use sqlite). To make things easier, we will also use the Chromedriver image that Drupal CI uses.
We want our Nightwatch tests to run if our CUSTOM_RUN_TESTS flag is set to true and we will run them only if the "Build Code" and "Manage Secrets" steps have completed successfully. Lastly, we want the pipeline to fail if the Nightwatch tests run into an issue and fail so we can catch code that breaks our application and prevent its deployment.
While our tests are executing, they may run into issues and fail. If that happens, we want to store the Nightwatch generated reports as artifacts so we can view from the Code Studio UI:
To prepare our tests to run, we will use the scripts from the Acquia AutoDevOps template to build the Drupal codebase and install Drupal. We will install yarn, which we can then use to install the Drupal javascript dependencies and run our tests, and we will make sure Chromedriver is updated (as the one that ships with Drupal may be old).
If you noticed above, we've also included some echo statements such as:
These add any output from the commands between them into collapsable sections in the Code Studio logs so the logs can be easier to read and kept relatively clean, since what we care about the most is the output of our tests. We wrap everything else in sections like these as well. If there's an issue with any of the commands at any point, we can expand the section to take a look.
Finally, we can configure Drupal's Nightwatch environment variables by creating the expected .env file in the core directory and adding them inside. We will check the status of Chromedriver and Drupal to ensure we are ready and install Drupal core's Javascript dependencies and run our tests. We will start the PHP server that is included with Drupal core and configure it to serve Drupal on the same address and port we told Nightwatch to use as the Drupal base URL (http://127.0.0.1:8080). We will install the Javascript dependencies and run our tests.
Make note that we will run only the tests we previously tagged with "myproject" as we don't want to run other tests that may be included in core itself or contributed modules.
-
Putting it all together
Putting all of the above together our final .gitlab-ci.yml file should look like this:
-
Troubleshooting
If for some reason the tests are not running or failing without any clear reason, we can use the following to verify the status of Drupal, Chromedriver, as well as the environment variables that are being used to run the tests.
In addition, we can adapt the Nightwatch command to run in verbose mode to see if there's any other issues that we can't immediately identify.