Applying the Automated Testing Kit Recipe

Do you prefer to watch a video of these instructions? Click here.

System Requirements

  • a container server such as Docker or OrbStack (required by DDEV)
  • DDEV (the recipe requires DDEV, which is a tool that makes Drupal development convenient)
  • NodeJS (using Homebrew to install Node it is convenient).

Install all three packages above before continuing. The recipe sets up a working Drupal instance only for Playwright tests. Use the instructions elsewhere in this documentation to set up Cypress manually if you want to experiment with Cypress tests.

Node will provide the tools npm, the Node Package Manager, and npx, Node Package eXecute.

The Automated Testing Kit Demonstration Recipe currently works only with Drupal 10.4 (December, 2024). It is suitable for a vanilla Drupal installation or simply to test the Kit. Note that the Demo Recipe installs test data and additional modules that you'll need to delete and disable if you start building with a site created by the recipe.

For existing sites, we recommend following the instructions in Installation/Uninstallation and install only the modules necessary for the tests you want to run. We do not provide support using the recipe on an existing site; the recipe makes unique assumptions that may not apply to your installation. Please use the manual instructions instead. 

Adjust your directory names below as required.

cd ~/Sites
mkdir pl-atk-d104-demo
cd pl-atk-d104-demo
ddev config --project-type=drupal --php-version=8.3 --docroot=web
ddev composer create drupal/recommended-project:10.4

The commands above configure DDEV then install Drupal. Accept all the default options.

Next, start the containers, install Drush, set up the vanilla site and launch it:

ddev start
ddev composer require drush/drush
ddev drush site:install --account-name=admin --account-pass=password -y
ddev launch

We need to install the Unpack plugin:

ddev composer config allow-plugins.ewcomposer/unpack true 
ddev composer config repo.recipe-unpack vcs https://github.com/woredeyonas/Drupal-Recipe-Unpack.git 
ddev composer require ewcomposer/unpack:dev-master

We are ready to install the recipe. The Composer command below downloads the recipe and dependencies specified by the recipe. It installs the recipe in /recipes and installs the dependencies to their proper location on the file system i.e./recipes /modules/contrib.

ddev composer require drupal/automated_testing_kit_demo_recipe

Clear the cache:

ddev drush cr

The next Composer command moves the recipe dependency definitions (located in its composer.json file) into the project's composer.json file by unpacking the recipe.

ddev composer unpack drupal/automated_testing_kit_demo_recipe

Finally, apply the recipe; add "-v" to the end if you want to see details of the installation:

ddev drush recipe ../recipes/automated_testing_kit_demo_recipe

The recipe:

  • Runs the atk_setup script located in contrib/automated_testing_kit/module_support. This script:
    • copies the tests into the project root (<project root>/tests)
    • copies playwright.config.js into the project root
    • copies playwright.atk.config.js into the project root
    • copies and renames playwright.package.json to package.json in the project root
  • Enables the Automated Testing Kit module
  • Enables and configures the contributed modules needed by Automated Testing Kit
  • Adds default content for tests to work (such as 403 and 404 pages plus some dummy search data)
  • Performs configuration of the 403 and 404 pages (at /admin/config/system/site-information)
  • Enables the Automated Testing Kit Demonstration submodule, which has a post-installation event subscriber that:
    • sets the site URL in playwright.config.js
    • adds "ddev" to drushCmd in playwright.atk.config.js
    • runs Cron to index the dummy data (so that the search tests work).

At this point, the Drupal installation has all the Drupal-specific modules and configuration it needs to run Automated Testing Kit tests. When you pull up the site, you'll see all the modules in the Extend page at /admin/modules.

There is some additional setup to run the Playwright tests. 

Install Playwright

Playwright requires Node so install that first. 

At this point, the correct package.json is in the project root directory. Install Playwright and its dependencies with:

npm update

Install the browsers Playwright needs:

npx playwright install

Accept the defaults.

The recipe updated the baseURL value in playwright.config.js. To see the value it used, type: 

ddev describe

You should see something like the following:

Run tests with one of the following commands:

npx playwright test
npx playwright test --grep "@ATK-PW-1050"

Or use Visual Studio Code with the Playwright Test Extension (which is excellent).

You will see output similar to the following:

Running 21 tests using 5 workers