Skip to content

Testing

FedMS has several layers of testing. The active stack is:

Layer Tool Where Status
Coding standards phpcs tests/phpcs.files Active
Static analysis phpstan tests/phpstan.neon + per-module phpstan.neon Active
Unit / Kernel / Functional phpunit tests/phpunit.xml.dist Active
Visual regression BackstopJS tests/backstop/ Available
End-to-end Playwright tests/playwright/ Active, preferred
End-to-end Cypress tests/cypress/ Deprecated

Per-module tests

Test a single FedMS module:

1
2
3
l3d ahoy test phpcsmodule fedms_task
l3d ahoy test phpstanmodule fedms_task
l3d ahoy test phpunitmodule fedms_task

The NAME you pass is the top-level directory name under web/modules/contrib/. The command resolves the path automatically.

For modules with submodules (e.g. eca has eca_content, eca_form, etc.), always pass the parent module name — the commands cover all submodules under that directory.

Coding standards

phpcs is configured per the Drupal Coding Standards. The file list to scan is in tests/phpcs.files.

Common fixes:

1
2
l3d phpcs --standard=Drupal --extensions=php,module,inc,install,test,profile,theme web/modules/contrib/fedms_X
l3d phpcbf --standard=Drupal --extensions=php,module,inc,install,test,profile,theme web/modules/contrib/fedms_X

(But prefer the ahoy test phpcsmodule wrapper.)

Static analysis

phpstan is configured per-module in <module>/phpstan.neon, with a shared base at tests/phpstan.neon. The current target level is the Drupal recommended level for the relevant module version.

Run per-module:

1
l3d ahoy test phpstanmodule fedms_task

To bump the analysis level for a module, edit its phpstan.neon.

PHPUnit

PHPUnit test discovery follows the Drupal convention:

1
2
3
4
<module>/tests/src/Unit/
<module>/tests/src/Kernel/
<module>/tests/src/Functional/
<module>/tests/src/FunctionalJavascript/

Some modules have no PHP tests yet — that's a backlog item. New PHP should ship with tests where reasonable.

Playwright (E2E)

The active E2E suite. Lives at tests/playwright/ and at its own GitLab project fedms/components/tests/playwright.

Branch conventions

Both Playwright and Cypress (while it exists) use:

Branch Purpose
develop Simple smoke tests that run on every FedMS site daily.
feature/advanced Full role-based tests that run on the demo site on a fresh install.

The feature/advanced branch is never merged back into develop — develop is merged forward into feature/advanced when needed.

Running locally

1
2
3
cd tests/playwright
l3d npm install
l3d npx playwright test

(Adapt the exact invocation to the suite's package.json.)

Writing new tests

  • New tests go to Playwright, not Cypress.
  • Pick the right branch:
  • Smoke test that should run on every site → develop.
  • Advanced role-based test → feature/advanced.
  • Use the page-object pattern established in the suite.

BackstopJS (visual regression)

Available for catching visual regressions. The config is in tests/backstop/. Run when intentionally changing themed pages to update the reference screenshots:

1
2
3
4
cd tests/backstop
l3d npm install
l3d npx backstop reference     # capture new references
l3d npx backstop test          # compare current to references

Tests in CI

The CI pipeline (defined in fedms/components/scripts/fedms.gitlab-ci.yml) runs the relevant test layers on every push:

  • phpcs on every PHP module.
  • phpstan on every PHP module.
  • phpunit on every module that ships tests.
  • Playwright smoke tests on the deployed site (post-deploy).

If a job fails, fix the issue locally before pushing again. See Contributing for the failure-remediation flow.

Deployment tests

A planned third layer of testing — deployment tests — runs nightly against every customer site, against a copy of the live database, to verify that the next update won't break the site. See fedms/components/profile#20.

End-to-end tests for documented behavior

A future session of work will write Playwright tests that verify this documentation as the spec — every documented user journey will have a corresponding test. See the Roadmap for the tracking.

Next steps