Getting Started

Minimal Setup

Installation Add to composer.json:

"require": {
    "sensiolabs/behat-page-object-extension": "^2.0"
}

Run composer update.

Enable Extension In behat.yml:

extensions:
    SensioLabs\Behat\PageObjectExtension: ~

First Page Object Create a class in features/bootstrap/Page/ (e.g., LoginPage.php):

<?php
namespace Features\Page;

use Behat\MinkExtension\Page\Page;

class LoginPage extends Page
{
    public function getUrl() { return '/login'; }

    public function submitLogin($username, $password) {
        $this->fillField('username', $username);
        $this->fillField('password', $password);
        $this->pressButton('Login');
    }
}

First Feature Reference the page in a feature file:

Given I am on the login page
When I submit login "user" "pass123"

Where to Look First

Official Docs: Behat Page Object Extension
Example Project: Clone the demo repo for a working example.
Bootstrap Directory: All page objects and hooks live in features/bootstrap/.

First Use Case: Login Flow

Create LoginPage (as above).

Write a step definition:

// features/bootstrap/FeatureContext.php
use Features\Page\LoginPage;

$this->getSession()->getPage()->loginPage = function () {
    return new LoginPage($this->getSession());
};

Use in feature:

Given I am on the login page
When I submit login "user" "pass123"
Then I should see "Welcome, user"

Implementation Patterns

Page Object Structure

Organize pages by feature/module:

features/
├── bootstrap/
│   ├── Page/
│   │   ├── Auth/
│   │   │   ├── LoginPage.php
│   │   │   └── DashboardPage.php
│   │   └── Admin/
│   │       └── UserManagementPage.php
│   └── FeatureContext.php

Common Workflows

1. Reusable Page Components

Extract shared UI elements into Page Components:

// features/bootstrap/Page/Component/Navbar.php
namespace Features\Page\Component;

use SensioLabs\Behat\PageObjectExtension\Page\Page;

class Navbar extends Page
{
    public function clickAdminLink() {
        $this->clickLink('Admin');
    }
}

Use in a page:

// features/bootstrap/Page/AdminPage.php
class AdminPage extends Page
{
    public function getNavbar() {
        return $this->getSubPage($this->getSession(), Navbar::class);
    }
}

2. Dynamic Page Factories

Generate pages dynamically based on URLs or parameters:

// features/bootstrap/Page/UserProfilePage.php
class UserProfilePage extends Page
{
    public function __construct($session, $userId) {
        $this->userId = $userId;
        parent::__construct($session);
    }

    public function getUrl() {
        return "/profile/{$this->userId}";
    }
}

$this->getSession()->getPage()->userProfilePage = function ($userId) {
    return new UserProfilePage($this->getSession(), $userId);
};

3. Hooks for Page Initialization

Use BeforeScenario to preload pages:

// features/bootstrap/FeatureContext.php
use Behat\Behat\Hook\Scope\ScenarioScope;

beforeScenario(ScenarioScope $scope) {
    $page = $scope->getEnvironment()->getContext()->getSession()->getPage();
    $page->loginPage = new LoginPage($page->getSession());
}

4. Integration with Mink

Leverage Mink’s drivers (e.g., Selenium, Guzzle) for assertions:

// In a page object
public function assertTitleContains($text) {
    $this->assertSession()->titleContains($text);
}

5. Data-Driven Tests with Pages

Pass data via Given steps:

Given I am on the login page with credentials "user1" "pass1"

// FeatureContext.php
public function iAmOnTheLoginPageWithCredentials($username, $password) {
    $page = $this->getSession()->getPage()->loginPage;
    $page->open();
    $page->submitLogin($username, $password);
}

Gotchas and Tips

Pitfalls

1. Session Management

Issue: Pages may lose session context if not properly initialized.
Fix: Always pass the $session object to page constructors:
```
new LoginPage($this->getSession());
```

2. Circular Dependencies

Issue: Pages referencing each other (e.g., LoginPage → DashboardPage → LoginPage) cause errors.
Fix: Use dependency injection via getSubPage() or lazy-load pages.

3. Stale Elements

Issue: Mink elements become stale if the page reloads.

Fix: Use waitForElement() or waitFor():

$this->waitForElementVisible('#element');

4. URL Hardcoding

Issue: Hardcoded URLs break in multi-environment setups.

Fix: Use getParameter() in getUrl():

public function getUrl() {
    return $this->getParameter('base_url') . '/login';
}

Debugging Tips

1. Enable Mink Debugging

Add to behat.yml:

default:
    extensions:
        Behat\MinkExtension:
            base_url: http://localhost
            goutte: ~
            selenium2: ~
            debug: true  # <-- Enable debug

2. Log Page Actions

Add debug logs to page methods:

public function submitLogin($username, $password) {
    \Behat\Behat\Temporary\Output\ConsoleOutput::getInstance()->writeln(
        "Submitting login for: $username"
    );
    $this->fillField('username', $username);
    // ...
}

3. Verify Session Context

Check if the session is active:

// In FeatureContext.php
public function assertSessionIsActive() {
    $this->getSession()->start();
    $this->assertTrue($this->getSession()->isStarted());
}

Configuration Quirks

1. Custom Page Paths

Override default Page/ directory in behat.yml:

extensions:
    SensioLabs\Behat\PageObjectExtension:
        paths:
            - %paths.base%/custom/page/dir

2. Autoloading Pages

Ensure autoloading is configured in composer.json:

"autoload": {
    "psr-4": {
        "Features\\": "features/bootstrap"
    }
}

3. Parameter Injection

Pass Behat parameters to pages:

// In getUrl()
public function getUrl() {
    return $this->getParameter('app.base_url') . '/login';
}

Define parameters in behat.yml:

default:
    parameters:
        app.base_url: http://example.com

Extension Points

1. Custom Page Classes

Extend SensioLabs\Behat\PageObjectExtension\Page\Page for shared logic:

// features/bootstrap/BasePage.php
abstract class BasePage extends \SensioLabs\Behat\PageObjectExtension\Page\Page
{
    public function assertElementExists($selector) {
        $this->assertSession()->elementExists($selector);
    }
}

2. Step Definitions for Pages

Create reusable steps:

// features/bootstrap/PageSteps.php
use Features\Page\LoginPage;

$loginPage = new LoginPage($this->getSession());

Given(/^I am on the login page$/) {
    $loginPage->open();
};

When(/^I login as "([^"]*)" with password "([^"]*)"$/) {
    $loginPage->submitLogin($arg1, $arg2);
};

3. Event Dispatching

Trigger events when pages load:

// In a page constructor
public function __construct($session) {
    parent::__construct($session);
    $this->getSession()->getEventDispatcher()->dispatch(
        'page.loaded',
        new PageEvent($this)
    );
}

4. Integration with Laravel

Share page objects between

Behat Page Object Extension Laravel Package