From df3980db68958d828650870dcb2efae6e9883c0f Mon Sep 17 00:00:00 2001 From: Johan Montenij Date: Sun, 24 May 2026 16:06:49 +0200 Subject: [PATCH] Add documentation about the pest --record command for browser test generation For implementation of the functionality, see https://github.com/pestphp/pest-plugin-browser/pull/222 This documentation should target the 5.x-docs. --- browser-recording.md | 120 +++++++++++++++++++++++++++++++++++++++++++ browser-testing.md | 2 + documentation.md | 1 + 3 files changed, 123 insertions(+) create mode 100644 browser-recording.md diff --git a/browser-recording.md b/browser-recording.md new file mode 100644 index 0000000..0f8d30d --- /dev/null +++ b/browser-recording.md @@ -0,0 +1,120 @@ +--- +title: Browser Recording +description: +--- + +# Browser Recording + +Pest can generate browser tests automatically by recording your interactions with the application. Run the following +command to start a recording session: + +```bash +vendor/bin/pest --record +``` + +Pest auto-starts an HTTP server with `APP_ENV=testing` — the same environment used when running browser tests — opens a +browser at full-screen resolution, and records every click, fill, navigation, selection, and assertion as you interact +with the application. When you close the browser, Pest prompts for a test description and an output file, then writes +the generated test to `tests/Browser/`. + +A typical generated test looks like this: + +```php +it('may create a new post', function () { + $this->visit('/posts/create') + ->fill('#title', 'Hello World') + ->fill('#body', 'My first post.') + ->click('Publish') + ->assertSee('Post created successfully'); +}); +``` + +## Options + +| Option | Default | Description | +|------------------------|-------------------|-------------------------------------------------------------| +| `--url=` | auto | Skip the auto-server; connect to this URL instead | +| `--visit=` | `/` | Path to open on start | +| `--test-id-attribute=` | `id` | HTML attribute used for element selectors | +| `--device=` | — | Emulate a device (e.g. `"iPhone 15"`) | +| `--viewport=` | screen resolution | Viewport size in pixels (e.g. `1280,800`) | +| `--auth` / `--user` | — | Start the browser pre-authenticated as a factory user | +| `--auth-script=` | — | Path to a custom auth bootstrap script (non-Laravel apps) | +| `--env=` | `testing` | Environment for the auto-started server | +| `--migrate-fresh` | — | Run `migrate:fresh` before opening the browser | +| `--seed` | — | Seed the database after `--migrate-fresh` | +| `--browser=` | `chrome` | Browser to record with: `chrome`, `firefox`, or `safari` | +| `--channel=` | — | Browser channel (e.g. `msedge`, `chrome-canary`) | +| `--lang=` | — | Override the browser locale (e.g. `fr`, `nl`) | +| `--timezone=` | — | Override the browser timezone (e.g. `Europe/Paris`) | +| `--color-scheme=` | — | Preferred color scheme: `dark`, `light`, or `no-preference` | + +## Authenticated Recording + +Browser tests run against an isolated `APP_ENV=testing` database, so users that exist in your local database are not +present when the test runs. The `--auth` flag solves this without requiring a manual login flow: before the browser +opens, Pest bootstraps the Laravel app, creates a factory user, starts a session authenticated as that user, and injects +a valid session cookie into the browser — so the browser starts pre-authenticated. + +```bash +vendor/bin/pest --record --auth --visit=/dashboard +``` + +The generated test automatically uses `actingAs` so no real credentials are needed and the test works in any +environment: + +```php +it('may view the dashboard', function () { + $this->actingAs(\App\Models\User::factory()->create()); + + $this->visit('/dashboard') + ->assertSee('Welcome back'); +}); +``` + +`--user` is an alias for `--auth`. + +## Fresh Database + +To record against a predictable, clean dataset, combine `--migrate-fresh` with `--seed`: + +```bash +vendor/bin/pest --record --migrate-fresh --seed --visit=/dashboard +``` + +This runs `php artisan migrate:fresh` (and optionally `db:seed`) before the browser opens, giving you a known starting +state for your recording. + +## Recording in a Specific Browser + +```bash +vendor/bin/pest --record --browser=firefox +vendor/bin/pest --record --browser=chrome --channel=msedge +``` + +## Recording with Locale, Timezone, or Color Scheme + +You can override the browser's locale, timezone, and color scheme to record tests that target specific regional or +accessibility scenarios: + +```bash +vendor/bin/pest --record --lang=fr --timezone=Europe/Paris +vendor/bin/pest --record --color-scheme=dark +``` + +## Recording Against an Existing Server + +Pass `--url=` to skip the auto-started server entirely and connect to a running instance. This is useful when you have +Laravel Herd, Valet, or an existing `php artisan serve` process: + +```bash +vendor/bin/pest --record --url=http://localhost:8000 --visit=/dashboard +``` + +Please be aware that test usually run against an isolated `APP_ENV=testing` database, so if you connect to a running +instance with a different environment, the generated test may not work as expected without additional configuration. + +--- + +Now, let's dive into the full browser testing API, including assertions, interactions, and +debugging: [Browser Testing](/docs/browser-testing) diff --git a/browser-testing.md b/browser-testing.md index 943b716..8ed7fb5 100644 --- a/browser-testing.md +++ b/browser-testing.md @@ -79,6 +79,8 @@ For debugging purposes, you can run the tests in a headed mode and pause the exe ./vendor/bin/pest --debug ``` +You can also generate browser tests automatically by recording your interactions with the application. For more information, see [Browser Recording](/docs/browser-recording). + ### Navigation The `visit()` method is used to navigate to a specific URL in your browser test. It provides various methods to interact with the page: diff --git a/documentation.md b/documentation.md index fd32619..cb80d27 100644 --- a/documentation.md +++ b/documentation.md @@ -27,6 +27,7 @@ - [Plugins](/docs/plugins) - [Team Management](/docs/team-management) - [Browser Testing](/docs/browser-testing) + - [Browser Recording](/docs/browser-recording) - [Architecture Testing](/docs/arch-testing) - [Stress Testing](/docs/stress-testing) - [Test Coverage](/docs/test-coverage)