Download the PHP package zenstruck/browser without Composer

zenstruck/browser

Functional testing with Symfony can be verbose. This library provides an expressive, auto-completable, fluent wrapper around Symfony's native functional testing features:

Combine this library with zenstruck/foundry to make your tests even more succinct and expressive:

Installation

Optionally, enable the provided extension in your phpunit.xml:

• PHPUnit 8 or 9 :

• PHPUnit 10+ :

This extension provides the following features:

1. Intercepts test errors/failures and saves the browser's source (and screenshot/js console log if applicable) to the filesystem.
2. After your test suite is finished, list of summary of all saved artifacts (source/screenshots/js console logs) in your console.

Usage

This library provides 2 different "browsers":

1. KernelBrowser: makes requests using your Symfony Kernel (fast).
2. PantherBrowser: makes requests to a webserver with a real browser using symfony/panther which allows testing javascript (slow).

You can use these Browsers in your tests by having your test class use the HasBrowser trait:

All browsers have the following methods:

KernelBrowser

This browser has the following methods:

Authentication

The KernelBrowser has helpers and assertions for authentication:

Troubleshooting Authentication

LogicException: Cannot create the remember-me cookie; no master request available. exception when calling ->assertAuthenticated()

This is caused when the token is a RememberMeToken, lazy: true in your firewall, and the previous request didn't perform any security-related operations. Possible solutions:

1. Before calling ->assertAuthenticated(), visit a page you know initiates security (ie is_granted() in a Twig template).
2. Call ->withProfiling() before making the previous request. This enables the security data collector which performs security operations.
3. Set framework.profiler.collect: true in your test environment. This enables the profiler for all requests removing the need to ever call ->withProfiling() but can slow down your tests.

HTTP Requests

The KernelBrowser can be used for testing API endpoints. The following http methods are available:

Json Assertions

Make assertions about json responses using JMESPath expressions See the JMESPath Tutorials to learn more.

[!NOTE] mtdowling/jmespath.php is required: composer require --dev mtdowling/jmespath.php.

[!NOTE] See the full zenstruck/assert expectation API documentation to see all the methods available on Zenstruck\Browser\Json.

PantherBrowser

[!NOTE] The PantherBrowser is experimental in 1.0 and may be subject to BC Breaks.

[!TIP] By default, Panther will not start a web server if it detects one already running with the Symfony CLI. This is likely running in your dev environment and will cause unexpected test failures. Set the env variable BROWSER_ALWAYS_START_WEBSERVER=1 to always start a webserver configured for your current test env when running Panther tests.

This browser has the following extra methods:

Multiple Browser Instances

Within your test, you can call ->xBrowser() methods multiple times to get different browser instances. This could be useful for testing an app with real-time capabilities (ie websockets):

Configuration

There are several environment variables available to configure:

Extending

Test Browser Configuration

You can configure default options or a starting state for your browser in your tests by overriding the xBrowser() method from the HasBrowser trait:

Components

Components are objects that wrap common tasks into a component object. These extend Zenstruck\Browser\Component and can be injected into a browser's ->use() callable:

Mailer Component

See https://github.com/zenstruck/mailer-test#zenstruckbrowser-integration.

Custom Components

You may have pages or page parts that have specific actions/assertions you use quite regularly in your tests. You can wrap these up into a Component. Let's create a CommentComponent as an example to demonstrate this feature:

Access and use this new component in your tests:

Custom HttpOptions

If you find yourself creating a lot of http requests with the same options (ie an X-Token header) there are a couple ways to reduce this duplication:

1. Use ->setDefaultHttpOptions() for the current browser:

2. Use ->setDefaultHttpOptions() in your test case's default browser configuration:

3. Create a custom HttpOptions object:

   Then, in your tests:

4. Create a custom browser with your own request method (ie ->apiRequest()).

Custom Browser

It is likely you will want to add your own actions and assertions. You can do this by creating your own Browser that extends one of the implementations. You can then add your own actions/assertions by using the base browser methods.

Then, depending on the implementation you extended from, set the appropriate env variable:

• KernelBrowser: KERNEL_BROWSER_CLASS
• PantherBrowser: PANTHER_BROWSER_CLASS

For the example above, you would set KERNEL_BROWSER_CLASS=App\Tests\AppBrowser.

[!TIP] Create a base functional test case so all your tests can use your custom browser and use the @method annotation to ensure your tests can autocomplete your custom methods:

Extensions

These are traits that can be added to a Custom Browser.

Mailer Extension

See https://github.com/zenstruck/mailer-test#zenstruckbrowser-integration.

Custom Extension

You can create your own extensions for repetitive tasks. The example below is for an AuthenticationExtension to login/logout users and make assertions about a users authenticated status:

Add to your Custom Browser:

Use in your tests: