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. PlaywrightBrowser: drives a real browser with playwright-php/playwright-symfony but passes its requests to your Symfony Kernel, so no webserver is required (slow).

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

Both browsers have the following methods:

Authentication

Both browsers have 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.

Session

Both browsers can inject your app's http session into ->use(), to read what the app stored or to set something up before making a request:

The session is loaded from the session cookie if the browser already has one, so the id is preserved and nothing the app stored is lost. It is saved, and its cookie written, when the callback returns.

[!NOTE] This requires the session to be enabled in your app, and a session storage that the test process can write to, typically session.storage.factory.mock_file in the test environment.

Exceptions

Exceptions thrown while handling a request are caught and converted to a response, as they are in production. Both browsers can turn this off:

Redirects

By default, redirects are followed. Both browsers can stop on them instead:

[!NOTE] While intercepting, the PlaywrightBrowser parks the real browser on the url that redirected and renders nothing, since no response is delivered to it. The status and Location are still available for assertions.

Profiling

Both browsers expose the Symfony profiler:

KernelBrowser

This browser has the following methods:

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.

PlaywrightBrowser

[!NOTE] The PlaywrightBrowser is experimental and may be subject to BC Breaks.

This drives a real browser so you can test javascript, but it does not start a webserver: requests made by the browser are intercepted and passed to your booted kernel. The browser therefore talks to the same application instance (and container) as your test, so mocked services, an in-memory database and the profiler behave as they do with the KernelBrowser.

It requires playwright-php/playwright-symfony (PHP 8.2+/Symfony 6.4+), Node.js 20+, and the Playwright browsers:

[!NOTE] If PlaywrightSymfonyBundle is registered and enabled, its configuration (base url, intercepted hosts, asset server) is used.

It requires your test to extend KernelTestCase (or WebTestCase):

[!WARNING] Do not extend Playwright\Symfony\Test\PlaywrightTestCase. It manages its own browser and sessions, which would conflict with the ones managed here - a LogicException is thrown if you try.

Choose the engine with the PLAYWRIGHT_BROWSER env variable (chromium (default), firefox or webkit), and set PLAYWRIGHT_HEADLESS=false to watch the browser as it runs.

This browser has the following extra methods:

[!NOTE] Uncaught javascript errors are not included in the console log: Playwright reports these as a separate pageerror event which playwright-php does not yet expose.

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):

Each playwrightBrowser() call gets its own browser context, isolated from the others in cookies and storage, while sharing one browser process. They also share the kernel booted for the test, so they see the same application state, just as separate browsers hitting one webserver would.

Parallel Testing

Both browsers work with ParaTest. Each worker is a separate PHP process with its own browser, launched only if that worker runs a test needing one.

Saved artifacts work as usual: each worker writes to the configured directories, and a failure still saves the source, screenshot and console log. The summary printed at the end of a serial run is not shown, as ParaTest does not surface worker output by then.

[!NOTE] Expect one browser per worker: --processes 8 means up to eight browsers, each with its own Node process, so pick a number your machine and CI runner can carry.

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
• PlaywrightBrowser: PLAYWRIGHT_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:

Security Policy

If you discover a security vulnerability, please do not open a public issue or pull request. Instead, please review this repository's Security Policy for instructions on how to report it responsibly.