Behat Test Runner Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev bex/behat-test-runner
   

   Add to behat.yml under your test suite:

   default:
     suites:
       default:
         contexts:
           - Bex\Behat\Context\TestRunnerContext
   

2. First Use Case: Create a feature file to test a Behat extension. Example:

   Feature: Testing a custom extension
     Scenario: Verify custom step execution
       Given I have the context:
           """
           <?php
           use Behat\Behat\Context\Context;
           class CustomContext implements Context {
               public function __construct() {}
               public function customStep() {}
           }
           """
       And I have the feature:
           """
           Feature: Custom step test
             Scenario:
               Given I execute a custom step
           """
       When I run Behat
       Then I should not see a failing test
   

Key Files to Review

• vendor/bex/behat-test-runner/src/Context/TestRunnerContext.php (core logic)
• Example feature files in the package’s tests/ directory (if any).

Implementation Patterns

Workflow for Testing Behat Extensions

1. Define Test Contexts: Use the TestRunnerContext to dynamically generate and test Behat contexts, features, and configurations.

   Given I have the context: "<?php ... ?>"
   And I have the feature: "Feature: ..."
   

2. Simulate Real Scenarios:

   • Test Mink/Behat-Mink interactions by provisioning HTML files:

     Given I have the file "index.html" in document root: "..."  # Embed HTML
     

   • Mock web servers:

     And I have a web server running on host "localhost" and port "8080"
     

3. Extension Testing:

   • Test custom extensions by embedding their configurations in behat.yml snippets:

     And I have the behat configuration:
         """
         extensions:
           MyVendor\MyExtension: ~
         """
     

4. Integration with Laravel:

   • Use the runner to test Laravel-specific Behat extensions (e.g., dusk, laravel-behat).
   • Example: Test a Laravel Dusk step by embedding its context and feature files.

5. CLI Options: Pass PHP CLI options to the nested Behat process:

   And I run Behat with options: ["-d", "memory_limit=-1"]
   

Common Patterns

• Isolation: Use workingDirectory to avoid conflicts with existing files:

  contexts:
    - Bex\Behat\Context\TestRunnerContext:
        workingDirectory: %paths.base%/tmp/test-runner
  

• Reusability: Store reusable context/feature snippets in variables or separate files, then embed them dynamically.
• Debugging: Leverage the runner’s output to inspect nested Behat’s logs:

  When I run Behat with verbose output
  

Gotchas and Tips

Pitfalls

1. Temporary Directory Handling:

   • Defaults to /tmp/behat-test-runner<...>. If not cleaned up, it may clutter your system.
   • Fix: Explicitly set workingDirectory in behat.yml for persistent testing:

     workingDirectory: %paths.base%/storage/behat-test-runner
     

2. Browser/Server Dependencies:

   • PhantomJS or other drivers must be installed and accessible via browserCommand.
   • Tip: Use Docker or local binaries for consistency:

     browserCommand: docker run --rm selenium/standalone-firefox
     

3. PHP Version Mismatches:

   • The nested Behat process uses the same PHP version as the host. Test with the same PHP version as your Laravel app.

4. Output Pollution:

   • Nested Behat’s output may interfere with the host process. Use Then I should not see a failing test to filter results.

5. Context Class Loading:

   • Dynamically generated contexts must be autoloadable. Ensure the workingDirectory is in your composer.json’s autoload paths or use relative paths.

Debugging Tips

• Inspect Working Directory: Access the working directory programmatically to debug file/context generation:

  $workingDir = \Bex\Behat\Context\TestRunnerContext::getWorkingDirectory();
  

• Verbose Mode: Enable verbose output to see nested Behat’s logs:

  When I run Behat with options: ["-vvv"]
  

• Cleanup Issues: If the working directory isn’t cleaned up, manually delete it or extend TestRunnerContext to override cleanup logic.

Extension Points

1. Custom Steps: Extend TestRunnerContext to add domain-specific steps. Example:

   namespace App\Tests\Behat;
   use Bex\Behat\Context\TestRunnerContext;
   
   class CustomTestRunnerContext extends TestRunnerContext {
       public function customStep() {
           // Add logic here
       }
   }
   

   Register it in behat.yml:

   contexts:
     - App\Tests\Behat\CustomTestRunnerContext
   

2. Pre/Post-Execution Hooks: Override beforeRun() or afterRun() in a custom context to modify the nested Behat’s environment.

3. Configuration Snippets: Create helper methods to generate reusable behat.yml snippets for your Laravel extensions.

Laravel-Specific Tips

• Artisan Integration: Use the runner to test Behat extensions that interact with Laravel’s Artisan commands. Example:

  And I have the behat configuration:
      """
      extensions:
        Behat\MinkExtension:
          base_url: http://laravel.test
      """
  

• Environment Variables: Pass Laravel’s .env variables to the nested Behat process via CLI options:

  And I run Behat with options: ["-d", "APP_ENV=testing"]
  

• Service Providers: Test Behat extensions that rely on Laravel service providers by embedding their configurations in the runner’s behat.yml.