[#690] Reclassified trait-specific composer dependencies as optional. (#691)

Author: AlexSkrypnyk

CONTRIBUTING.md

@@ -51,6 +51,15 @@ Run `ahoy lint-docs` to validate the format of the steps.
 - **Contains assertions**: Always use `Contains` or `NotContains` (e.g., `xmlAssertElementContains()`, `headerAssertNotContains()`)
 - Never use "DoesNot" or "DoNot" patterns - use "Not" prefix directly
 
+## Dependency policy
+
+Keep the `require` section of `composer.json` minimal - it should contain only what **every** consumer needs regardless of which traits they use.
+
+- **`require`**: the framework and browser abstraction that virtually all steps build on - `php`, `behat/behat`, `behat/mink`.
+- **`require-dev` + `suggest`**: any package used by only a subset of traits. List it in `require-dev` so this library's own test suite still exercises it, **and** in `suggest` with a message naming the exact trait(s) or step(s) that need it (as `justinrainbow/json-schema` does for `JsonTrait`).
+
+When a new trait needs a package, decide up front: trait-specific packages go in `require-dev` + `suggest`, never in `require`. Demoting a package from `require` to `suggest` later is a breaking change for consumers relying on transitive installation, so batch such demotions into the next major release and document them in [MIGRATION.md](MIGRATION.md).
+
 ## Local environment setup
 
 Install [Docker](https://www.docker.com/), [Pygmy](https://github.com/pygmystack/pygmy), [Ahoy](https://github.com/ahoy-cli/ahoy)

MIGRATION.md

@@ -1,5 +1,25 @@
 # Migration guide
 
+## Optional dependencies moved to `require-dev` and `suggest`
+
+Trait-specific packages are no longer hard `require` dependencies. They now live in `require-dev` (so this library's own test suite still runs) and `suggest`, matching the existing treatment of `justinrainbow/json-schema`. Projects that relied on transitive installation must add the packages they use to their own `composer.json`.
+
+| Package | Add it to your `require-dev` when you use |
+| --- | --- |
+| `drupal/drupal-extension` | any Drupal trait (`DrevOps\BehatSteps\Drupal\*`) |
+| `softcreatr/jsonpath` | `JsonTrait` JSON path steps (`the JSON path ... should ...`) |
+
+`@javascript` scenarios need a JavaScript-capable Mink driver. The steps are driver agnostic, so install **one** of these interchangeable drivers - both run the full `@javascript` suite and both are exercised by this library's CI:
+
+- `lullabot/mink-selenium2-driver` - drives a Selenium/WebDriver server.
+- `dmore/behat-chrome-extension` - drives headless Chrome directly over the Chrome DevTools Protocol, with no Selenium server.
+
+`behat/behat` and `behat/mink` remain hard `require` dependencies. For example, a project that uses the Drupal traits and runs JavaScript scenarios with headless Chrome adds:
+
+```bash
+composer require --dev drupal/drupal-extension dmore/behat-chrome-extension
+```
+
 ## Unified entity cleanup
 
 Traits that create Drupal entities now register them in a single shared registry and delete them in reverse creation order through one `entityCleanupAfterScenario` hook, instead of each trait running its own after-scenario cleanup.

README.md

@@ -114,6 +114,14 @@ from the community.
 composer require --dev drevops/behat-steps:^3
 ```
 
+### Optional dependencies
+
+To keep installs lean, packages needed by only some traits are declared as `suggest` rather than hard requirements (only `behat/behat` and `behat/mink` are required). Add the ones for the traits you use to your project's `require-dev` - run `composer suggests` to list them:
+
+- **Drupal traits** (`DrevOps\BehatSteps\Drupal\*`) need `drupal/drupal-extension`.
+- **`JsonTrait`** needs `softcreatr/jsonpath` for JSON path steps and `justinrainbow/json-schema` for JSON schema steps.
+- **`@javascript` scenarios** need a Mink driver - see [JavaScript drivers](#javascript-drivers) below.
+
 ## Usage
 
 Add required traits to your

composer.json

@@ -19,38 +19,42 @@
     "require": {
         "php": ">=8.2",
         "behat/behat": "^3.14",
-        "behat/mink": ">=1.11",
-        "dmore/behat-chrome-extension": "^1.4",
-        "drupal/drupal-extension": "^6.0",
-        "lullabot/mink-selenium2-driver": "^1.7.4",
-        "softcreatr/jsonpath": "^0.10 || ^1.0"
+        "behat/mink": ">=1.11"
     },
     "require-dev": {
         "alexskrypnyk/phpunit-helpers": "^0.15.0",
         "cweagans/composer-patches": "^2.0",
         "dantleech/gherkin-lint": "^0.2.3",
         "dealerdirect/phpcodesniffer-composer-installer": "^1",
+        "dmore/behat-chrome-extension": "^1.4",
         "drevops/behat-phpserver": "^2.1.1",
         "drevops/behat-screenshot": "^2.1",
         "drevops/phpcs-standard": "^0.7",
         "drupal/coder": "^8.3.28",
+        "drupal/drupal-extension": "^6.0",
         "dvdoug/behat-code-coverage": "^5.3.2.1",
         "ergebnis/composer-normalize": "^2.47",
         "justinrainbow/json-schema": "^6.0",
+        "lullabot/mink-selenium2-driver": "^1.7.4",
         "mglaman/phpstan-drupal": "^2.0.0",
         "php-parallel-lint/php-parallel-lint": "^1.4",
         "phpcompatibility/php-compatibility": "^9.3.5",
         "phpspec/prophecy-phpunit": "^2.3",
         "phpstan/extension-installer": "^1.4.3",
         "phpstan/phpstan": "^2.0.0",
         "phpunit/phpunit": "^11",
-        "rector/rector": "^2.0"
+        "rector/rector": "^2.0",
+        "softcreatr/jsonpath": "^0.10 || ^1.0"
     },
     "conflict": {
         "drupal/drupal-extension": "<6"
     },
     "suggest": {
-        "justinrainbow/json-schema": "Required by JsonTrait for JSON Schema validation steps ('the response should match the JSON schema ...')."
+        "dmore/behat-chrome-extension": "JavaScript driver for @javascript scenarios: drives headless Chrome directly over the Chrome DevTools Protocol (selenium-less). Interchangeable with lullabot/mink-selenium2-driver - install one.",
+        "drupal/drupal-extension": "Required by all Drupal step traits (src/Drupal/*), which build on the Drupal Extension RawDrupalContext and Drupal driver.",
+        "justinrainbow/json-schema": "Required by JsonTrait for JSON Schema validation steps ('the response should match the JSON schema ...').",
+        "lullabot/mink-selenium2-driver": "JavaScript driver for @javascript scenarios: drives a Selenium/WebDriver server. Interchangeable with dmore/behat-chrome-extension - install one.",
+        "softcreatr/jsonpath": "Required by JsonTrait for JSON path assertion steps ('the JSON path ... should ...')."
     },
     "autoload": {
         "psr-4": {

scripts/provision.sh

@@ -33,6 +33,11 @@ $fixture = json_decode(file_get_contents("/app/build/composer.json"), true);
 // Cherry-pick the required properties from the base composer.json.
 $package_filtered["require-dev"] = $package["require"];
 
+// Trait-specific runtime dependencies live in "require-dev" + "suggest" rather
+// than "require", so the fixture site - which exercises every trait - must pull
+// each suggested package back in to run the full Behat suite.
+$package_filtered["require-dev"] = array_merge($package_filtered["require-dev"], array_intersect_key($package["require-dev"], $package["suggest"]));
+
 // Deps required to run Behat tests.
 $package_filtered["require-dev"] = array_merge($package_filtered["require-dev"], array_filter($package["require-dev"], function ($ver, $name) {
   return in_array($name, [