Page Object Extension Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require friends-of-behat/page-object-extension --dev
   

2. Configure Behat: Add the extension to your behat.yml:

   extensions:
       FriendsOfBehat\PageObjectExtension:
           page_classes_prefix: 'App\Tests\Behat\Page'
           element_classes_prefix: 'App\Tests\Behat\Element'
   

3. Create a Page Class: Define a page class (e.g., src/Tests/Behat/Page/LoginPage.php):

   <?php
   namespace App\Tests\Behat\Page;
   
   use FriendsOfBehat\PageObjectExtension\Page\Page;
   
   class LoginPage extends Page
   {
       public function getUrl(): string
       {
           return '/login';
       }
   
       public function getEmailField()
       {
           return $this->findField('email');
       }
   }
   

4. Use in Feature Context: Reference the page in your context:

   use App\Tests\Behat\Page\LoginPage;
   
   /** @When I am on the login page */
   public function iAmOnTheLoginPage(LoginPage $page)
   {
       $page->open();
   }
   

First Use Case: Login Flow

1. Define Page: Extend Page or SymfonyPage for Symfony apps.
2. Define Elements: Use Element for reusable components (e.g., modals, forms).
3. Write Steps: Use dependency injection to interact with pages/elements in contexts.

Implementation Patterns

Page-Object Workflow

1. Page Hierarchy:
   • Use Page for full-page interactions (e.g., DashboardPage).
   • Use Element for reusable components (e.g., SidebarElement, SearchBarElement).
   • Example:

     // SidebarElement.php
     use FriendsOfBehat\PageObjectExtension\Element\Element;
     
     class SidebarElement extends Element
     {
         public function clickMenuItem(string $name)
         {
             $this->findLink($name)->click();
         }
     }
     

2. Symfony Integration:
   • Extend SymfonyPage for Symfony apps to leverage kernel/container:

     use FriendsOfBehat\PageObjectExtension\Page\SymfonyPage;
     
     class AdminPage extends SymfonyPage
     {
         public function getUrl(): string
         {
             return $this->getRouter()->generate('admin_dashboard');
         }
     }
     

3. Dependency Injection:
   • Annotate context methods with page/element types:

     /** @When I click :button on the :page */
     public function iClickButtonOnPage(Page $page, string $button)
     {
         $page->findButton($button)->click();
     }
     

Integration Tips

1. Reuse Elements Across Pages:
   • Define shared elements (e.g., HeaderElement) and inject them into multiple pages.
2. Parameterized Pages:
   • Use constructor arguments for dynamic pages:

     class ProductPage extends Page
     {
         public function __construct(private string $slug)
         {
         }
     
         public function getUrl(): string
         {
             return "/products/{$this->slug}";
         }
     }
     

3. Custom Assertions:
   • Extend Page to add domain-specific assertions:

     class CheckoutPage extends Page
     {
         public function assertOrderTotal(float $expected): void
         {
             $actual = $this->find('css', '.order-total')->getText();
             Assert::assertEquals($expected, $actual);
         }
     }
     

4. Symfony Fixtures:
   • Use SymfonyPage to generate URLs via Symfony’s router:

     $url = $this->getRouter()->generate('app_product_show', ['slug' => 'test']);
     

Gotchas and Tips

Common Pitfalls

1. Namespace Conflicts:
   • Ensure page_classes_prefix and element_classes_prefix in behat.yml match your autoload paths.
   • Example: If classes are in Tests/Behat/Page, set:

     FriendsOfBehat\PageObjectExtension:
         page_classes_prefix: 'Tests\Behat\Page'
     

2. Element Locators:
   • Avoid brittle selectors (e.g., id="user-email"). Prefer CSS or XPath with classes/attributes.
   • Example:

     $this->find('css', '.user-email-input')->sendKeys('test@example.com');
     

3. SymfonyPage Kernel:
   • If using SymfonyPage, ensure your AppKernel or KernelInterface is bootstrapped. Debug with:

     var_dump($this->getKernel()->getContainer()->has('router'));
     

4. Circular Dependencies:
   • Avoid pages/elements referencing each other directly. Use composition (e.g., inject HeaderElement into Page).

Debugging Tips

1. Element Not Found:
   • Use ->waitForElementVisible() or ->waitForElement() to handle dynamic content:

     $this->find('css', '.dynamic-element')->waitForElementVisible(10);
     

   • Debug with:

     var_dump($this->getPageSource()); // Dump HTML for inspection
     

2. Slow Tests:
   • Reduce waits by using explicit assertions:

     $this->assertElementVisible('css', '.loader', false); // Fail fast
     

3. Symfony Context Issues:
   • If SymfonyPage fails to resolve services, ensure your BehatContext extends SymfonyContext or has the kernel injected:

     use FriendsOfBehat\PageObjectExtension\Context\SymfonyContext;
     
     class FeatureContext extends SymfonyContext
     {
         // ...
     }
     

Extension Points

1. Custom Element Types:
   • Extend Element for domain-specific behaviors:

     class DataTableElement extends Element
     {
         public function getRowCount(): int
         {
             return $this->findAll('css', 'tr')->count();
         }
     }
     

2. Page Events:
   • Override open() or close() for pre/post-actions:

     class LoginPage extends Page
     {
         public function open(): void
         {
             $this->getSession()->start();
             parent::open();
         }
     }
     

3. Integration with Other Extensions:
   • Combine with Behat\MinkExtension for custom drivers or Behat\SymfonyExtension for Symfony-specific features.
   • Example: Use Mink in Element:

     $this->getSession()->getPage()->find('link', 'Sign Up');
     

4. Custom Assertions:
   • Add static methods to Page for reusable checks:

     class BasePage extends Page
     {
         public static function assertPageTitle(Page $page, string $expected)
         {
             Assert::assertEquals($expected, $page->getTitle());
         }
     }