Suite Settings Extension Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev friends-of-behat/suite-settings-extension
   

2. Configure in behat.yml Add the extension to your default suite configuration:

   default:
       extensions:
           FriendsOfBehat\SuiteSettingsExtension:
               paths:
                   - "%paths.base%/features"  # Override default paths
               contexts:
                   - "FeatureContext"       # Override default contexts
   

3. First Use Case Define a new suite in behat.yml that inherits these defaults:

   my_suite:
       extends: default
       suites:
           my_suite:
               paths: [ "%paths.base%/custom-features" ]  # Overrides only paths
   

   Run with:

   ./vendor/bin/behat -c behat.yml --suite=my_suite
   

Implementation Patterns

Workflow Integration

1. Suite Inheritance Use extends: default to inherit settings from the configured extension. Override only what’s needed (e.g., paths, contexts, or tags).

2. Environment-Specific Suites Dynamically set suite-specific configs via environment variables:

   # behat.yml
   test_suite:
       extends: default
       contexts:
           - "TestContext"
       suites:
           test_suite:
               paths: [ "%paths.base%/tests/features" ]
               tags: "@test"
   

3. Context Isolation Group contexts by feature type (e.g., AuthContext, PaymentContext) and reference them in suites:

   auth_suite:
       extends: default
       contexts:
           - "AuthContext"
       suites:
           auth_suite:
               paths: [ "%paths.base%/auth/features" ]
   

4. CLI Overrides Temporarily override settings via CLI:

   ./vendor/bin/behat -c behat.yml --suite=my_suite --contexts="FeatureContext,DebugContext"
   

Laravel-Specific Patterns

1. Dynamic Paths Use Laravel’s base_path() in behat.yml:

   default:
       extensions:
           FriendsOfBehat\SuiteSettingsExtension:
               paths:
                   - "%paths.base%/tests/Feature"  # Laravel's test features dir
   

2. Service Container Contexts Register Behat contexts as Laravel services (e.g., AuthContext) and reference them in suites:

   auth_suite:
       contexts:
           - "App\Services\AuthContext"
   

3. Environment-Based Suites Load suites conditionally based on Laravel’s .env:

   # behat.yml
   %env(APP_ENV) == 'testing'%:
       test_suite:
           extends: default
           contexts:
               - "TestContext"
   

Gotchas and Tips

Pitfalls

1. Path Resolution

   • Issue: Paths like "features" resolve relative to behat.yml, not the project root.
   • Fix: Use %paths.base% or absolute paths:

     paths:
         - "%paths.base%/features"  # Correct
         - "features"              # May fail if behat.yml isn’t in root
     

2. Context Loading Order

   • Issue: Contexts defined in default may conflict with suite-specific contexts.
   • Fix: Explicitly list all required contexts in each suite to avoid inheritance surprises.

3. Extension Configuration Overlap

   • Issue: Mixing FriendsOfBehat\SuiteSettingsExtension with other extensions (e.g., Behat\MinkExtension) may cause duplicate settings.
   • Fix: Ensure no duplicate paths or contexts are defined in multiple extensions.

4. Deprecated Syntax

   • Issue: Older Behat versions may not support YAML %env() syntax.
   • Fix: Use parameters in behat.yml for dynamic values:

     default:
         extensions:
             FriendsOfBehat\SuiteSettingsExtension:
                 paths:
                     - "%paths.base%/features/%behat.environment%"
     

Debugging Tips

1. Validate Suite Settings Run with --dry-run to inspect resolved settings:

   ./vendor/bin/behat --dry-run --suite=my_suite
   

2. Check Context Loading Enable verbose output to debug context loading:

   ./vendor/bin/behat -v --suite=my_suite
   

3. Isolate Suite Issues Test suites in isolation by creating minimal configs:

   # behat.minimal.yml
   my_suite:
       extensions:
           FriendsOfBehat\SuiteSettingsExtension:
               paths: [ "features" ]
       suites:
           my_suite:
               contexts: [ "FeatureContext" ]
   

Extension Points

1. Custom Suite Factories Extend the extension to support dynamic suite generation (e.g., per-module suites):

   // CustomExtension.php
   use FriendsOfBehat\SuiteSettingsExtension\SuiteSettingsExtension;
   
   class CustomSuiteSettingsExtension extends SuiteSettingsExtension {
       public function load(Loader $loader, array $config) {
           parent::load($loader, $config);
           // Add logic to generate suites dynamically
       }
   }
   

2. Environment-Aware Paths Override getPaths() in a custom extension to resolve paths based on Laravel’s storage paths:

   public function getPaths(array $config) {
       return [
           base_path('tests/Feature'),
           storage_path('features'),
       ];
   }
   

3. Tag-Based Suite Filtering Use the extension to enforce tag-based suite separation (e.g., @smoke, @regression):

   smoke_suite:
       extends: default
       suites:
           smoke_suite:
               tags: "@smoke"