Configuring GitLab To Run Drupal Test Traits For Your D8 Site

Drupal Test Traits enables Drupal developers to test existing Drupal sites with all the content, layout, and icons. This is extremely useful for content-centric sites with a massive amount of content where we need to check if the content is laid out correctly and the corresponding icons are showing up, plus the URLs are up and accessible. This is advantageous for PHP developers when compared to other options like Behat, where we have to learn Gherkin to write the tests. While Gherkin is useful, PHP developers would feel more comfortable writing tests in PHP. If you’re interested in Gherkin, we have written a bunch of articles on that as well.

In this tutorial, we will show you how to write a simple DTT assertion and how to run the tests automatically using Gitlab. 

Installing Drupal test traits

Assuming that you already have set up the target Drupal site using composer, run the following command.

composer require --dev 'weitzman/drupal-test-traits'

This will automatically install the required packages, and you are ready to start testing. 

Now fetch the phpunit.xml from the Weitzman repository and place it in your repo. Modify it according to the URL of the site. See the sample phpunit.xml for reference. 

In the above sample phpunit.xml, we have modified line #10 and line #11 to include the localhost URL. DTT will utilize this URL for running the tests. To be more specific, this would be the section having the variable DTT_BASE_URL and DTT_API_URL. These two are sufficient for now. 

Creating Tests

We are going to test if the home page is returning a 200 OK. Create a directory ‘tests’ outside of the web, and inside create the structure as follows. 

tests

   └── src

      └── Functional

           └── HomePageViewDisplayTest.php

The HomePageViewDisplayTest is where we write the actual tests and associated assertions. Inside the HomepageViewDisplayTest.php copy-paste the following code and replace the home-page-url with the URL of the homepage or any URL you want to test. 

The code should be self-explanatory. We are merely extending one of the ExistingSiteBase Class and adding an assertion to see if the URL is returning 200 OK. 

Other base classes can also be used. However, that is for a later tutorial as we are only covering the basics here. 

Running Tests on local 

Once we have written the tests, we then proceed to run and test the tests. To run the tests, we need to ensure that the following prerequisites are met: 

• A running instance of the site you need to test with the database and all the relevant content. 
• DTT package inside vendor folder of composer (Already covered above)
• PHPUnit package that comes with the Drupal vendor package (composer install --dev)
• Phpunit.xml (Modify it according to the localhost URL). This is the config file that allows PHPUnit to know what is the URL of the site. 

Of course, if you are developing a Drupal site, most of these artifacts should already be present. Just ensure that you have run composer install --dev. Once these are verified, run the command below. 

So in the above script, if we break it down, we are calling PHPUnit with the Test class we created earlier as an argument. For supporting the running of the tests, we are also specifying the path to phpunit.xml, which stores the PHPUnit configuration, followed by the bootstrap file. This determines how Drupal has to be bootstrapped and the namespace of the Drupal site. 

If all goes well, the tests will show how many assertions were run and how many were passed. 

Running Tests inside GitLab

To run the tests inside GitLab, we need to create a GitLab pipeline, which requires the following:

1. A docker image with the following
   1. A running web server instance (Apache or Nginx)
   2. A working database instance (MySQL or MariaDB)
   3. PHP 7.2
   4. Composer
   5. Drupal 8
       
2. Once we have the above available, we need to find a way to upload the database to this pipeline and install it in the. This has to be done since DTT requires a database. There are two ways to do this.
   1. Upload the database to dropbox or some other file hosting server to be accessed by wget or curl. This method is prolonged and only suitable for small databases as we need to download and install it each time. 
   2. We can upload a sanitized version of the database to a docker image and call the docker image in our Gitlab pipeline. This is the faster method as the image already comes with the preloaded database. However, we need to define a workflow where the database is sanitized and updated frequently in an automatic fashion
       
3. We also need a custom settings.php labeled settings.gitlab.php to load the specific settings when the site is being tested in the GitLab pipeline. This has to be brought into the working space by including it in settings.php conditionally. 

In our present example, we will follow the former method. Please have a look at the GitLab pipeline we have used for running DTT. 

If you can see the sample GitLab pipeline YAML file above, you will notice the following: 

1. We have used a public image which has most of the prerequisites including the Drupal stack juampynr/drupal8ci:latest
2. The image does not have a database. So rather than installing, we have used another Docker image (mysql:5.7) as a service. 
3. We need to define a few docker variables that we will be using in the settings.gitlabci.php. We took the MySQL settings from the documentation
4. After installing some additional dependencies, we proceed to start Apache. 
5. Next, we download the database from a host and import it
6. Once that is done, link the directory to the public HTML directory and install Drupal using composer. 
7. Once Drupal is installed, we clear the caches and run database updates.
8. Finally, the last line is where we write the script to test the execution, similar to how we did it on local. 
9. If all goes well, the pipeline job will be executed, and you will be having the tests running automatically. 

Conclusion

So the above is a simple example of how we can create test traits and automate the tests using GitLab. Stay tuned for more advanced tests that cover more features.

References

Introducing Drupal Testing Traits: Drupal extension for testing existing sites: https://www.previousnext.com.au/blog/introducing-drupal-testing-traits-drupal-extension-testing-existing-sites

Introducing Drupal Test Traits: https://medium.com/massgovdigital/introducing-drupal-test-traits-9fe09e84384c