smoke

Smoke adds automated browser testing to your Drupal site with minimal setup. Install the module and run one setup command, then run ddev drush smoke to verify your site: homepage loads, login works, forms submit, commerce and search work, and more. Tests run in a real browser (Chromium via Playwright) with a live progress bar, and results appear in an admin dashboard or in your terminal. It's built for teams using Drupal on DDEV who want to quickly confirm that updates or deployments didn't break the site.

⚠️ DDEV is currently required. Smoke's setup and test execution rely on DDEV. Support for other local development environments (Lando, DKAN, bare metal) is planned but not yet available. If you're not using DDEV, this module won't work for you yet.

Quick Start

3 commands. 5 minutes. You're done.

# 1. Install
ddev composer require drupal/smoke
ddev drush en smoke -y

# 2. Setup (one-time, downloads browser)
ddev drush smoke:setup

# 3. Run tests
ddev drush smoke --run

That's it. You'll see a progress bar and results in your terminal.

What Setup Does

The ddev drush smoke:setup command is a one-time process that takes 2-5 minutes on first run. Here's what happens:

1. Checks environment — Verifies DDEV is running and Node.js is available
2. Installs npm dependencies — Downloads Playwright and test utilities (~50 MiB)
3. Downloads Chromium — One-time download of the browser binary (~180 MiB). Cached per-user inside DDEV, shared across projects
4. Installs system libraries — Chromium needs libraries like libnss3 and libatk. Smoke installs these automatically
5. Configures webform — If Webform module is enabled, prompts for which webform to test (or creates smoke_test)
6. Scans your site — Detects installed modules (Commerce, Search API, etc.) and generates test configuration
7. Creates test user — Sets up smoke_bot user and role for authentication tests
8. Installs DDEV hook — Adds .ddev/config.smoke.yaml so config auto-regenerates on ddev start
9. Copies Playwright to project root — Suites and config copied so VS Code/Cursor can discover tests
10. Installs host command — Adds ddev smoke-ide-setup; run it once on your host for the IDE
11. Runs global Playwright setup — In container (skips if already installed). If you don't use global Playwright on your host, setup shows a tip with the path to run bash <path>/global-setup.sh from your project root (you can adjust the path when prompted)

What gets installed where:

• smoke/playwright/node_modules/ — npm packages (~50 MiB)
• ~/.cache/ms-playwright/ — Chromium browser inside container (~180 MiB, shared across projects)
• smoke/playwright/.smoke-config.json — Generated test config (<1 KB)
• .ddev/config.smoke.yaml — DDEV post-start hook (<1 KB)
• .ddev/commands/host/smoke-ide-setup — Host command for IDE (run once on host)

Re-running setup: If you add new modules (Webform, Commerce, etc.), run ddev drush smoke:setup again. It skips the browser download and just regenerates the test config.

Auto-recovery: If browser launch fails during tests (e.g., missing dependencies after ddev restart), Smoke automatically reinstalls dependencies and retries.

Optional Extras

View results in browser:

# Open: /admin/reports/smoke

Run just one suite:

ddev drush smoke:suite auth
ddev drush smoke:suite webform

Quick sanity check (fastest):

ddev drush smoke --run --quick

Test your staging/production site:

ddev drush smoke --run --target=https://mysite.pantheonsite.io

VS Code / Cursor users:

ddev smoke-ide-setup          # Run once on your host (after setup) so the IDE discovers tests
ddev drush smoke:init         # Enables IDE test discovery and custom test directory

Running ddev smoke-ide-setup on your host requires Node.js 18+ (the script will error with nvm instructions if older). For global Playwright on your Mac (optional), setup prints a tip with bash <path>/global-setup.sh from project root; you can adjust the path when prompted.

Features

What problem does Smoke solve?

After a composer update, config change, or deployment, you need a fast way to know if the site still works. Smoke runs a set of browser tests and reports in seconds what works and what's broken.

Basic functionality

• Runs Playwright browser tests against your Drupal site
• Auto-detects installed modules (Webform, Commerce, Search API, etc.) and runs only relevant tests
• Shows results in Reports → Smoke Tests or via Drush with a live progress bar
• Creates a smoke_bot test user for authentication tests
• Auto-fixes common issues like empty sitemaps with drush smoke:fix

Unique features

• Zero-config detection — Enable the module, run setup, and Smoke figures out what to test
• Self-sufficient setup — Installs only Chromium (~180 MiB) directly; no third-party DDEV addons required
• Auto-recovery — If browser launch fails, Smoke automatically reinstalls dependencies and retries
• Plugin system — Add custom test suites via PHP attributes or YAML; agencies can add site-specific tests without modifying the module
• VS Code / Cursor integration — ddev smoke-ide-setup (run once on host) and drush smoke:init set up project-level Playwright config so IDE extensions discover your tests
• Remote testing — Run the same tests against a live or staging URL
• Accessibility checks — Built-in axe-core WCAG 2.1 AA scans on homepage and login page
• Webform auto-creation — When Webform is enabled, Smoke creates a smoke_test form and tests it
• Auto-fix command — drush smoke:fix analyzes failures and repairs common issues (e.g. regenerates sitemaps)
• CI integration — JUnit XML export (--junit) and HTML reports (--html) for CI pipelines
• Custom URLs — Add your own pages to test via the settings form
• PHPUnit tests — Module ships with its own test suite, runnable via drush smoke:unit

When and why use this module?

• After running composer update on contrib modules
• Before and after deployments to staging or production
• As a quick health check for support teams managing multiple Drupal sites
• To catch PHP errors, broken images, mixed content, or JavaScript errors on key pages

Use cases

• "Did that security update break the login page?"
• "Does checkout still work after the Commerce upgrade?"
• "Is the homepage returning 200 with no PHP fatals?"
• "Are there critical accessibility violations on the login page?"

Additional Requirements

• DDEV (required) — Smoke currently only works with DDEV. The setup command handles Chromium, npm dependencies, and system libraries inside the DDEV container. Support for other environments is planned.
• Drupal 10 or 11
• Composer (via DDEV)
• Node/npm — Inside the DDEV container for running tests (setup installs it). If you run ddev smoke-ide-setup on your host for VS Code/Cursor, you need Node.js 18+ on the host; the script uses .nvmrc when present and will prompt you to switch if your Node is too old.

Recommended modules/libraries

• Webform — Adds webform test suite
• Drupal Commerce — Adds Commerce tests
• Search API or Search — Adds search page tests
• Simple Sitemap or XML Sitemap — Adds sitemap tests (with dashboard regeneration button and drush smoke:fix --sitemap)

Smoke detects these automatically; no configuration needed.

Adding Custom Test Suites

Agencies and developers can add custom test suites without modifying the Smoke module:

Option 1: PHP Plugin

Create a class in your custom module at src/Plugin/SmokeSuite/MySuite.php with the #[SmokeSuite] attribute:

use Drupal\smoke\Attribute\SmokeSuite;
use Drupal\smoke\Plugin\SuiteBase;

#[SmokeSuite(
  id: 'my_agency_suite',
  label: 'My Agency Tests',
  description: 'Custom tests for agency sites',
)]
class MyAgencySuite extends SuiteBase {
  public function isDetected(): bool {
    return TRUE; // or check for specific conditions
  }
}

Option 2: YAML Definition

Create smoke.suites.yml in your module or project root:

my_agency_suite:
  label: 'My Agency Tests'
  description: 'Custom tests for agency sites'
  spec_path: 'playwright-smoke/suites/my-agency.spec.ts'

Option 3: Project-level tests

Run drush smoke:init to create a playwright-smoke/ directory at your project root with example spec files. These are auto-discovered.

Similar projects

• PHPUnit / Nightwatch — Developer-focused unit/functional tests; Smoke runs higher-level browser tests with minimal setup
• Behat / Drupal Extension — BDD-style tests requiring custom scenarios; Smoke has built-in suites and one command
• Lighthouse, Pa11y — Accessibility/performance audits; Smoke includes axe-core as one suite among many, integrated into Drupal admin and Drush

Smoke's differentiator: one setup command, one run command, broad coverage — no test authoring required. But when you need custom tests, the plugin system makes it easy.

Supporting this Module

(Leave blank or add your support link.)

Community Documentation

• README in the repository (includes full uninstall/cleanup guide)
• CHANGELOG
• Issue queue

Drush commands:

• drush smoke — Status landing page
• drush smoke --run — Run all tests with live progress bar
• drush smoke --run --quick — Quick sanity check (core_pages + auth only)
• drush smoke:list — See detected suites
• drush smoke:suite [name] — Run one suite
• drush smoke:setup — Set up Playwright
• drush smoke:copy-to-project — Copy to project root for IDE (used by ddev smoke-ide-setup)
• drush smoke:init — Initialize for VS Code/Cursor
• drush smoke:fix — Auto-fix common issues
• drush smoke:unit — Run the module's PHPUnit tests
• drush smoke --run --suite=SUITE — Run specific suites
• drush smoke --run --parallel — Run suites in parallel (faster)
• drush smoke --run --watch — Watch mode for test development
• drush smoke --run --junit=/path/to/results.xml — CI-friendly JUnit XML output
• drush smoke --run --html=/path/to/report — Interactive HTML report
• drush smoke --run --target=URL — Run against a remote site

Test suites (auto-detected): Core Pages, Authentication, Webform, Commerce, Search, Health, Sitemap, Content, Accessibility