Pickle Panther Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require amoifr/pickle-panther-bundle
   

   Add to config/bundles.php if not auto-discovered:

   Amoifr\PicklePantherBundle\PicklePantherBundle::class => ['all' => true],
   

2. Create a Scenario File Place a YAML file in tests/E2E/Scenario/ (e.g., homepage.yaml):

   scenarios:
     - nom: "Homepage loads successfully"
       contexte:
         navigateur: desktop
       etapes:
         - action: "Visits the page with the [/]"
         - action: "Checks that the text [Welcome] is present in the selector [h1]"
   

3. Write a Test Class Extend BasePantherTest and run the scenario:

   use Amoifr\PicklePantherBundle\Test\BasePantherTest;
   
   final class HomepageTest extends BasePantherTest {
       public function testHomepage(): void {
           $this->createScenarioRunner()->runTest(__DIR__.'/Scenario/homepage.yaml');
       }
   }
   

4. Run Tests

   php bin/phpunit tests/E2E/Scenario/HomepageTest
   

First Use Case: Basic Page Interaction

Use the bundle to test a homepage by:

• Defining a YAML scenario with steps like navigation and assertions.
• Implementing a #[Sentence] provider (see below) to handle the actions.
• Generating an HTML report after execution.

Implementation Patterns

1. Sentence Providers

Create services annotated with #[Sentence] to map YAML actions to PHP logic. Example:

use Amoifr\PicklePantherBundle\Attribute\Sentence;

#[Sentence('Visits the page with the [/]')]
#[Sentence('Visits the page with the [/contact]')]
class PageVisitProvider {
    public function visitPageWithPath(string $path, PantherClient $client): void {
        $client->request('GET', $path);
    }
}

• Tagging: Use #[Sentence] with the exact YAML action string (supports placeholders like [/]).
• Dependency Injection: Inject PantherClient or other services as needed.

2. Context Handling

Define context-specific logic (e.g., desktop/mobile) via:

• Context Providers: Implement ContextProviderInterface to modify the PantherClient before scenario execution.

  use Amoifr\PicklePantherBundle\Context\ContextProviderInterface;
  
  class MobileContextProvider implements ContextProviderInterface {
      public function applyContext(array $context, PantherClient $client): void {
          $client->setBrowserEngine('chrome', ['options' => ['deviceScaleFactor' => 2]]);
      }
  }
  

• Register Providers: Tag them with #[AsContextProvider] and map them in config/packages/pickle_panther.yaml:

  pickle_panther:
      context_providers:
          mobile: Amoifr\PicklePantherBundle\Context\MobileContextProvider
  

3. Dynamic Arguments

Pass dynamic values via YAML args or placeholders:

- action: "Checks that the text [text] is present in the selector [selector]"
  args:
    text: "Welcome"
    selector: "h1"

• Provider Method Signature: Match arguments to method parameters:

  #[Sentence('Checks that the text [text] is present in the selector [selector]')]
  public function checkTextInSelector(string $text, string $selector, PantherClient $client): void {
      $client->assertSelectorTextContains($selector, $text);
  }
  

4. Reporting

Generate HTML reports by configuring the ScenarioRunner:

$runner = $this->createScenarioRunner();
$runner->setReportPath(__DIR__.'/reports');
$runner->runTest($yamlPath);

• Reports include screenshots, step logs, and pass/fail status.

5. Integration with Symfony

• Kernel Boot: The bundle auto-configures during Kernel::boot().
• Test Isolation: Use PantherTestCase for browser isolation per test.
• Parallelization: Run scenarios in parallel by leveraging PHPUnit’s --parallel flag.

Gotchas and Tips

Pitfalls

1. Sentence Mismatches

   • Issue: YAML actions must exactly match #[Sentence] tags (including placeholders).
   • Fix: Use tools like phpstan to validate sentence providers or enable strict mode in config/packages/pickle_panther.yaml:

     pickle_panther:
         strict_sentence_matching: true
     

2. Context Overrides

   • Issue: Context providers may conflict if not properly prioritized.
   • Fix: Explicitly order providers in config/packages/pickle_panther.yaml:

     pickle_panther:
         context_providers_order: [mobile, desktop]
     

3. Dynamic Argument Parsing

   • Issue: Placeholders like [/path] must align with provider method signatures.
   • Fix: Use named placeholders (e.g., [path]) and ensure provider methods accept them in order:

     #[Sentence('Visits the path [path]')]
     public function visitPath(string $path, PantherClient $client): void { ... }
     

4. Report Path Conflicts

   • Issue: Overwriting reports if paths aren’t unique.
   • Fix: Use timestamps or UUIDs in report paths:

     $runner->setReportPath(__DIR__.'/reports/' . uniqid());
     

Debugging Tips

1. Enable Verbose Logging Configure in config/packages/pickle_panther.yaml:

   pickle_panther:
       debug: true
   

   Logs appear in var/log/pickle_panther.log.

2. Inspect the Sentence Registry Dump registered sentences during test setup:

   $registry = $this->get(SentenceRegistry::class);
   dump($registry->getSentences());
   

3. Panther-Specific Issues

   • Use PantherTestCase for browser isolation.
   • Handle flaky selectors with retries:

     $client->waitFor(10)->until(
         fn() => $client->has('css', $selector)
     );
     

Extension Points

1. Custom Assertions Extend PantherClient or create a new #[Sentence] provider for domain-specific assertions.

2. Plugin System Override ScenarioRunner to add pre/post hooks:

   $runner = $this->createScenarioRunner();
   $runner->addPreScenarioHook(function() { /* setup */ });
   $runner->addPostScenarioHook(function() { /* teardown */ });
   

3. Localization Add support for additional languages by extending the SentenceParser and updating YAML validators.

4. CI Integration Upload reports to artifacts (e.g., GitHub Actions):

   # .github/workflows/tests.yml
   - uses: actions/upload-artifact@v3
     with:
       name: e2e-reports
       path: tests/E2E/reports/