Automated testing

Test directory structure¶

From BLT 12.x, automated testing functionality is moved to plugins. Therefore, you must add plugins by running one or more of the following commands:

composer require acquia/blt-behat

composer require acquia/blt-drupal-test

This directory contains all projects tests, grouped by testing technology. For all configuration related to builds that actually run these tests, see the blt directory.

tests
├── behat - contains all Behat tests
│    ├── features
│    │   ├── bootstrap
│    │   └── Example.feature
│    ├── behat.yml - contains behat configuration common to all behat
|    |               profiles
│    └── integration.yml - contains behat configuration for the
|                          integration profile, which is used to run
|                          tests on the integration environment
└── phpunit - contains PHPUnit tests for the project (Drupal PHPUnit
              tests should reside within a given Drupal module)

Additional technologies (some of which won’t be supported by BLT) can also have their tests bundled in the tests folder for convenience (for example, tests/jmeter).

BLT also supports the bundling and execution of phpunit tests from locations outside of the tests folder. For additional information, see the PHPUnit configuration section of this page.

Executing tests¶

Before attempting to execute any tests, verify that Composer dependencies are built by running composer install in the project root directory.

The following testing commands are available for use:

• blt tests:all
• blt tests:behat:run
• blt tests:phpunit:run
• blt tests:drupal:run
• blt tests:security:check:updates
• blt tests:security:check:composer

Behat¶

The high-level purpose of BDD is to create a strong connection between business requirements and the actual tests. Behat tests should mirror ticket acceptance criteria as closely as possible.

Consequently, proper Behat tests should be written using business domain language. The test should be comprehensible by the stakeholder and represent a clear business value. It should represent a typical user behavior and need not be an exhaustive representation of all possible scenarios.

See referenced materials for more information on BDD best practices.

blt tests:behat:run -D behat.paths=${PWD}/tests/behat/features/Examples.feature
# Relative paths are assumed to be relative to tests/behat/features.
blt tests:behat:run -D behat.paths=Examples.feature

blt tests:behat:run -D behat.paths=${PWD}/tests/behat/features/Examples.feature:4
# Relative paths are assumed to be relative to tests/behat/features.
blt tests:behat:run -D behat.paths=Examples.feature:4

./vendor/bin/behat -c tests/behat/local.yml tests/behat/features/Examples.feature -p local

Unit and functional testing¶

PHPUnit¶

Project level, functional PHPUnit tests are included in tests/phpunit. Any PHPUnit tests that affect specific modules or application level features should be placed in the same directory as that module or feature code, not in this directory.

You can customize the tests:phpunit:run command by modifying your BLT configuration for the tests:phpunit key.

Each row under the tests:phpunit key should contain a combination of the following properties:

• bootstrap: A “bootstrap” PHP file run before the tests.
• class: The class name for the test.
• config: Path to either the Core phpunit configuration file (docroot/core/phpunit.xml.dist) or a custom one. If left blank, no configuration will be loaded with the unit test.
• debug: If true, will display debugging information.
• directory: Directory to scan for tests.
• exclude: Run tests excluding any tagged with this @group.
• file: The source file that declares the class provided in class.
• filter: Allows text filter for tests.
• group: Run tests only tagged with a specific @group.
• path: The directory where the phpunit command will be run from.
• printer: The TestListener implementation to use.
• stop-on-error: If true, will stop execution upon first error.
• stop-on-failure: If true, sill stop execution upon first error or failure.
• testdox: If true, report test execution progress in TestDox format.
• testsuite: Run tests that are part of a specific @testsuite.
• testsuites: (array) Run tests from multiple @testsuite``s (takes precedence over ``testsuite).

For additional information, see the PHPUnit documentation.

tests:
  phpunit:
    - # Run BLT"s example test.
      path: '${repo.root}/tests/phpunit'
      config: '${docroot}/core/phpunit.xml.dist'
      class: 'ExampleTest'
      file: 'ExampleTest.php'

Testing Drupal with PHPUnit¶

Each row under the tests:drupal key should contain a combination of the following properties (see Drupal’s core/phpunit.xml.dist for additional details):

• test-runner: Whether to run Drupal tests with PHPUnit (phpunit) or Drupal’s run-tests.sh script (run-tests-script).
• sudo-run-tests: Whether or not to use sudo when running Drupal tests.
• web-driver: WebDriver to use for running Drupal’s functional JavaScript tests (only chromedriver is supported).
• browsertest-output-directory: Directory to write output for browser tests (value for BROWSERTEST_OUTPUT_DIRECTORY).
• apache-run-group: Unix user used for tests (value for APACHE_RUN_USER).
• apache-run-user: Unix group used for tests (value for APACHE_RUN_GROUP). If sudo-run-tests:true, this is used to run testing commands as sudo -u www-data -E ./vendor/bin/phpunit {...}.
• mink-driver-args: Driver args to mink tests (value for MINK_DRIVER_ARGS).
• mink-driver-args-webdriver: Driver args to webdriver tests (value for MINK_DRIVER_ARGS_WEBDRIVER).
• mink-driver-class: Driver class for mink tests (value for MINK_DRIVER_CLASS).
• simpletest-base-url: Base URL of Simpletest (value for SIMPLETEST_BASE_URL).
• simpletest-db: Connection string Simpletest database (value for for SIMPLETEST_DB).
• symfony-deprecations-helper: Setting to disabled disables deprecation testing completely (value for SYMFONY_DEPRECATIONS_HELPER).
• phpunit: Tests to run using Drupal’s implementation of PHPUnit. This requires Drupal to be installed.
• drupal-tests: Tests to run with Drupal’s run-test.sh script.

tests:
  drupal:
    phpunit:
      - # Run Drupal' unit, kernel, functional, and functional-javascript testsuites for the action module.
        path: '${docroot}/core'
        config: ${docroot}/core/phpunit.xml.dist
        testsuites:
          - 'unit'
          - 'kernel'
          - 'functional'
          - `functional-javascript`
        group: action
      - # Run all tests in the custom modules directory.
        path: '${docroot}/core'
        config: ${docroot}/core/phpunit.xml.dist
        directory: ${docroot}/modules/custom

tests:
  drupal:
    drupal-tests:
      - # Run the PHPUnit-Unit, PHPUnit-Kernel, and PHPUnit-Functional test types for the action module.
        color: true
        concurrency: 2
        types:
          - 'PHPUnit-Unit'
          - 'PHPUnit-Kernel'
          - 'PHPUnit-Functional'
        tests:
          - 'action'
        sqlite: '${tests.drupal.sqlite}'
        url: '${tests.drupal.simpletest-base-url}'
      - # Run the PHPUnit-FunctionalJavascript test type for the action module.
        color: true
        concurrency: 1
        types:
          - 'PHPUnit-FunctionalJavascript'
        tests:
          - 'action'
        sqlite: '${tests.drupal.sqlite}'
        url: '${tests.drupal.simpletest-base-url}'
      - # Run the Simpletest test type for the user module.
        color: true
        concurrency: 1
        types:
          - 'Simpletest'
        tests:
          - 'user'
        sqlite: '${tests.drupal.sqlite}'
        url: '${tests.drupal.simpletest-base-url}'

Front-end testing¶

BLT supports a frontend-test target that can be used to execute several testing frameworks. Examples include Jest, Jasmine, Mocha, and Chai.