Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
128 lines (93 loc) · 4.4 KB

CONTRIBUTING.md

File metadata and controls

128 lines (93 loc) · 4.4 KB

Contributing

Below are some guidelines for developing and maintaining the Behat steps.

Steps format

A consistent steps format is essential for the readability and maintainability of tests. Follow these guidelines:

  • General Guidelines:

    • Avoid using regular expressions to define a step definition. Use tuple format instead for better clarity and maintainability.
    • Use descriptive placeholder names to help users quickly understand the expected value: content_type instead of type.
    • Use the following for tabled content.
    • For anything identified by a property, use with: Then the link : link with the title :title should exist
    • Avoid optional words like (the|a). Provide a single form instead to ensure consistency.
    • Omit unnecessary suffixes like on the page since it is implied.
    • All method names should begin with the trait name: userAssertHasRoles() for UserTrait.

  • Given:

    • Defines test prerequisites—conditions or data that must exist before the test runs.
    • Use words like exists or have.
    • Avoid using should or should not (these are reserved for assertions).
    • Refrain from using Given I (reserved for actions).

  • When:

    • Describes an action and must contain an action verb.
    • Use the format When I <verb>.

  • Then:

    • Specifies assertions and expectations.
    • Use should and should not to clearly indicate assertions.
    • Start the step with the entity being asserted, e.g., Then the link with a title :title exists.
    • Avoid using Then I.
    • Methods should include the Assert prefix, e.g., userAssertHasRoles().

We have some automated check for the steps format. Run ahoy lint-docs to validate the format of the steps.

Assertion Method Naming Conventions

  • Existence assertions:
    • Singular subjects → Exists or NotExists (e.g., fieldAssertExists(), vocabularyAssertNotExists())
    • Plural subjects → Exist or NotExist (e.g., termsAssertExist())
  • Contains assertions: Always use Contains or NotContains (e.g., xmlAssertElementContains(), headerAssertNotContains())
  • Never use "DoesNot" or "DoNot" patterns - use "Not" prefix directly

Local environment setup

Install Docker, Pygmy, Ahoy and shut down local web services (Apache/Nginx, MAMP etc)

Use ahoy --help to see the list of available commands.

Running tests

There are two types of tests in this repository: unit tests and Behat tests.

Unit tests

Unit tests are run using PHPUnit installed in the root of the repository and are independent of the Drupal version. This allows us to use the latest features of PHPUnit.

ahoy test-unit          # Run all unit tests

ahoy test-unit-coverage # Run tests with code coverage

Behat tests

Behat tests are used as functional/integration tests to validate the functionality of the traits. These Behat tests run in the same way they would be run in your project: traits are included into FeatureContext.php and then ran on the pre-configured fixture Drupal site using test features.

Run ahoy build to setup a fixture Drupal site in the build directory.

ahoy test-bdd                # Run all Behat tests

ahoy test-bdd path/to/file   # Run all Behat scenarios in specific feature file

ahoy test-bdd -- --tags=wip  # Run all Behat scenarios tagged with `@wip` tag

Debugging tests

  • ahoy debug
  • Set breakpoint
  • Run tests with ahoy test-bdd - your IDE will pickup an incoming debug connection

Updating fixture site

  • Build the fixture site and make the required changes
  • ahoy drush cex -y
  • ahoy update-fixtures to copy configuration changes from build directory to the fixtures directory

Validating and updating documentation

The available steps documentation is generated automatically from the source code.

The steps format is validated as well.

ahoy update-docs  # Update documentation

ahoy lint-docs    # Check documentation for errors