Skip to content

Git Hooks

This repository uses managed hooks from .githooks.

Hook policy: - .githooks/ is reserved for Git hook entrypoints and hook-facing commands. - Focused session test execution scripts live in scripts/testing/.

One-time setup

Run from repository root:

git config core.hooksPath .githooks
chmod +x .githooks/pre-push scripts/testing/run-tests.sh scripts/testing/ready-to-run.sh scripts/testing/check-orphan-test-assets.sh
npm ci

Required local tools outside Composer and npm packages: - shellcheck - yamllint

Focused session test commands:

bash scripts/testing/bootstrap-runtime.sh
bash scripts/testing/run-phpunit.sh tests/src/Unit/DeploymentUrlBuilderTest.php
bash scripts/testing/run-functional.sh tests/src/Functional/DeployRouteAccessTest.php

Behavior

  • On git push, .githooks/pre-push runs scripts/testing/ready-to-run.sh, which then delegates test execution to scripts/testing/run-tests.sh.
  • The push is blocked if any coding standards check, static analysis, or test fails.
  • Default mode is changed-files only (--changed) for faster local pushes:
    • skips checks when no validation-relevant files changed
    • runs eslint, stylelint, markdownlint-cli2, yamllint, shellcheck, and repository docs link checks only for matching changed files
    • runs php -l for changed PHP files
    • runs phpcs for changed PHP-like files and only fails on violations in changed lines
    • runs phpstan static analysis on all module code (full scan)
    • runs only affected test suites when possible
  • Full mode runs repository linting, docs link checks, PHP syntax validation, Drupal coding standards, static analysis, and all PHPUnit suites.
  • PHPUnit and PHPStan are not line-aware, so hooks run full scans for these tools.
  • When the installed PHPUnit version supports --display-deprecations, the runner enables explicit deprecation reporting during suite execution.
  • PHPCS memory usage is configurable via DRUPALFORGE_PHPCS_MEMORY_LIMIT (default 512M).
  • Kernel/Functional runtime prerequisites are auto-managed by runner:
    • default SIMPLETEST_DB is supplied when unset
    • BROWSERTEST_OUTPUT_DIRECTORY is automatically set to $DRUPALFORGE_RUNTIME_BUILD_DIR/sites/simpletest/browser_output for Functional suite HTML/screenshot artifacts
    • functional web server is started/stopped automatically with readiness probe
    • overrides supported via SIMPLETEST_DB, SIMPLETEST_BASE_URL, DRUPALFORGE_TEST_SERVER_PORT
  • Runtime artifacts are preserved by default for speed ($DRUPALFORGE_RUNTIME_BUILD_DIR, default vendor/drupal/drupal, and optional COMPOSER_CACHE_DIR).
    • Optional cleanup: set DRUPALFORGE_TEST_ARTIFACT_CLEANUP=build|cache|all (default none); cache applies only when COMPOSER_CACHE_DIR is set.
  • Documentation link checks validate repository-local relative links in Markdown files, while ignoring external URLs for deterministic runs.
  • PHPUnit failure gating is baseline-based, not allowlist-based.
    • Expected failing-test counts are stored in scripts/testing/baselines/failure-baseline.json.
    • Changed-line failure hits always block.
    • New or increased failing-test keys block.
    • Decreased counts also block until the baseline is reset.
  • Yamllint and shellcheck gating are baseline-based and count-based.
    • Expected yamllint counts are stored in scripts/testing/baselines/yamllint-baseline.txt as file|rule count.
    • Expected shellcheck counts are stored in scripts/testing/baselines/shellcheck-baseline.txt as file|SCxxxx count.
    • New or increased counts block.
    • Decreased counts also block until the corresponding baseline is reset.

Helper command

To run the pre-push "ready to run on GitLab" checklist:

scripts/testing/ready-to-run.sh

Optional flags:

scripts/testing/ready-to-run.sh --no-tests
scripts/testing/ready-to-run.sh --full

--no-tests runs structural/documentation checks only. --full runs both changed-mode and full suites.

Hierarchy summary: - scripts/testing/run-tests.sh is the canonical validation engine. - scripts/testing/ready-to-run.sh is a wrapper for pre-push readiness checks and orchestrates whether to run changed/full engine modes. - .githooks/pre-push is the hook entrypoint that invokes the wrapper.

To reset the repository-tracked PHPUnit failure baseline explicitly:

chmod +x scripts/testing/reset-phpunit-baseline.sh
scripts/testing/reset-phpunit-baseline.sh

To skip confirmation prompt:

scripts/testing/reset-phpunit-baseline.sh --yes

This command re-runs Unit, Kernel, and Functional suites, rebuilds scripts/testing/baselines/failure-baseline.json, and naturally prunes keys that no longer fail.

To reset YAML and shell lint baselines explicitly:

scripts/testing/reset-yamllint-baseline.sh --yes
scripts/testing/reset-shellcheck-baseline.sh --yes

Code Coverage

Generate code coverage reports for all test suites:

DRUPALFORGE_COVERAGE=1 ./scripts/testing/run-tests.sh

Coverage is written to coverage/ directory with HTML and Clover XML formats per test suite. Coverage is disabled by default and only generated during full test runs to keep development iteration fast.

  • To force full checks before pushing:
DRUPALFORGE_HOOK_FULL=1 git push