| Understand what ATK is and when to use it |
Overview |
Use ATK for ready-made Drupal E2E tests (login, forms, CRUD, menus, search, caching, sitemaps) plus Cypress/Playwright helpers; never enable ATK or qa_accounts on production — it serves data/ files, including qaUsers.json, to anonymous users. |
| Decide between ATK, Lullabot's playwright-drupal, or core's test tools |
Ecosystem & Alternatives |
Choose ATK for a Drupal-aware Cypress/Playwright test catalog, Lullabot/playwright-drupal for isolated parallel test sites, or core PHPUnit to stay in PHP. Nightwatch is not deprecated — core accepted a policy to replace it with Playwright, but nothing has landed yet. |
| Pick Cypress or Playwright as the runner |
Cypress vs Playwright |
Pick Playwright for new ATK projects — the larger 2.1 catalog (6 FedRAMP spec files against 4) and core's accepted policy both point that way. Keep Cypress only for an existing suite; ATK ships both catalogs but atk_setup writes package.json per runner, so running both overwrites the first. |
| Pick the right ATK release, or run on 2.0.0 stable |
Versions & Compatibility |
This guide targets 2.1.0-beta5 (2026-02-04); latest stable is 2.0.0 (2025-05-15). Use 2.1.0-beta for FedRAMP tests, Feeds, or Tugboat; on a 2.0.0 site the pre-flight filename, setup project and file:create don't exist, so 2.1 instructions break there. |
| Install ATK on a Drupal site |
Installation |
Install with the demo recipe on a fresh site (needs minimum-stability dev for performant-labs/qa_accounts:dev-main), or install drupal/qa_accounts:^1.1 yourself on an existing site, then run module_support/atk_setup playwright and npm install. Test sites only. |
| Configure the target site and Drush access |
Runner Configuration |
.atk.config.js sets drushCmd, Url routes, email and the pantheon/targetSite/tugboat blocks; execDrush() tries Pantheon, then SSH targetSite, then Tugboat, then drushCmd, in that order. baseURL lives in the runner's own config, not *.atk.config.js. |
| Run and extend the pre-flight check |
Pre-flight Checks |
The pre-flight runs inside the test run, not via a Drush command — Playwright's setup project calls preflightTest() before chromium; Cypress checks in a global before(). Only eq conditions are implemented; there is no drush atk:preflight command in any release. |
| Use ATK's preprocess hooks to find IDs in markup |
Selector Hooks |
ATK adds no generic test attribute — only two preprocess hooks: body classes like node-nid-42 on node/term routes, and data-media-id on images tied to a media entity. Read them with atkCommands.getNid()/getMid() or cy.getNid()/getMid(); ATK never added data-qa-id. |
| Find the test that fits my use case |
Test Catalog |
39 Playwright test declarations (38 active, 18 spec files) and 37 Cypress declarations (36 active, 17 files) cover register/login, contact, error pages, sitemap, caching, entity CRUD, menu, search and feeds — no logout, role-access, admin, forms, navigation, revision or scheduling suite exists. Tags are uneven upstream. |
| Use the helper functions |
Helper Functions |
Playwright ships 27 helpers in atk_commands.js (login, execDrush, config, users, nodes/media, assertions, preflightTest, skipIfLocal) plus 4 in atk_utilities.js. Never call Drush with execSync or cy.exec — it bypasses the Pantheon, SSH and Tugboat routing; read credentials from data/qaUsers.json, never hardcode them. |
| Write custom Drupal-aware tests |
Custom Tests |
Keep custom tests in directories without the atk_ prefix — atk_setup … back copies all of tests/atk/, tests/support/ and tests/data/* back into the module, so project helpers and data belong outside those two directories, for example tests/project-support/. |
| Snapshot databases with Testor |
Testor Snapshots |
Testor is a separate Robo CLI (performantlabs/testor), not an ATK or Drush command — install with composer require performantlabs/testor, then testor snapshot:create/list/get/restore/delete. The default snapshot:create --env=@self runs drush sql:sanitize on your LOCAL database before dumping it; run it on a throwaway copy. |
| Run ATK in CI |
CI Integration |
ATK ships no GitHub Actions workflow and no ddev-atk addon — build your own against ddev/github-action-setup-ddev, or route Drush through the tugboat or pantheon config block. Never add a drush atk:preflight CI step; the pre-flight runs inside npx playwright test itself. |
| Use the FedRAMP tests and other 2.1 features |
FedRAMP & 2.1 Features |
2.1.0-beta adds FedRAMP-oriented tests (rapid login, CORS/CSRF, session termination, unauthorized access, HTTPS redirect, security headers), Feeds tests and Tugboat routing — Playwright ships 6 FedRAMP spec files, Cypress 4. A green run covers some control areas; it is not an audit, and 2.1 has had betas only since 2025-08-05. |
| Migrate from Cypress to Playwright |
Cypress → Playwright Migration |
Preprocess hooks, drushCmd/pantheon/targetSite/tugboat config, preflightTests.yml, qaUsers.json and Testor snapshots carry over unchanged — only test bodies need translation. Playwright's execDrush() returns stdout directly instead of chaining like a Cypress command. |
| Add visual regression on top of ATK |
Visual Regression Layering |
ATK ships no visual-regression layer — no test takes a screenshot baseline. Layer native Playwright toHaveScreenshot(), Lullabot's VisualDiffTestCases, or a custom pixelmatch script on top; ATK's getUserPage() handles the login, Playwright's API does the VR. |
| Avoid common mistakes |
Anti-Patterns |
The most repeated ATK mistakes: following dead PerformantLabs GitHub URLs, running drush atk:preflight or drush testor:*, selecting [data-qa-id], enabling ATK or qa_accounts on production, and treating a green FedRAMP run as compliance certification. |
| Find module files, commands and URLs |
Code Reference |
Canonical source is git.drupalcode.org/project/automated_testing_kit, not GitHub — PerformantLabs' own atk-cypress/atk-playwright repos 404. ATK defines exactly two Drush commands, file:properties and file:create; check drush list --filter=file to confirm on your install. |