Skip to content
Diff Stage
Sign inCreate an account

Installing Diff Stage in a Laravel project

Connect your Laravel repository to Diff Stage, install the Pest browser recorder, and check your first local recording before adding GitHub Actions.

Guide 1 of 33 min readPest 5 · Browser 5.1.2

On this page

Check your project requirements

This guide uses Pest 5. The recorder also supports Pest 4 with Browser 4.3.1.

  • A Laravel project hosted on GitHub
  • Composer, Node.js and npm
  • Pest 5 with Browser 5.1.2
  • PHP 8.4 or later with the sockets extension
  • An app that runs in its test environment with disposable test data

Diff Stage records Pest browser tests so reviewers can watch the flow a pull request changes. Start by connecting your repository and installing the recorder. Then add the GitHub Actions recording workflow.

Check what you already have:

Terminalshell
php -v
php -m
composer show pestphp/pest
composer show pestphp/pest-plugin-browser

If you have no Pest browser tests yet, follow Pest’s browser testing setup first. Use the supported Browser version above rather than installing an unrestricted version.

Connect your GitHub repository#

Sign in at Diff Stage and select the team that will own the evidence. Choose a plan in setup if your team does not have one.

A team owner or admin can choose Connect GitHub, install the Diff Stage GitHub App and select repositories. Complete the GitHub flow and check that your repository appears as connected in Diff Stage. Your selection must fit the team’s repository allowance.

Install the recorder#

Add the recorder’s GitHub repository to Composer, then install the version used by this guide:

Terminalshell
composer config repositories.diff-stage vcs https://github.com/diff-stage/recorder
composer require --dev "diff-stage/recorder:dev-main#10e02da13722139b2f872fc155eb264056e42e3b" -W

-W allows Composer to update related dependencies, including PHPUnit, to satisfy Pest. Review and commit the resulting composer.json and composer.lock changes.

For Browser 5.1.2, install Playwright and Chromium:

Terminalshell
npm install --save-dev playwright@1.63.0
npx playwright install chromium

Commit your npm manifest and lockfile too. Linux machines missing browser libraries can use npx playwright install --with-deps chromium.

Check one recording locally#

Pick an existing browser test that exercises a real user flow. Replace this example path with your test:

Terminalshell
./vendor/bin/pest tests/Browser/CheckoutTest.php --record-videos

The default output directory is tests/Browser/Videos. Each recorded test produces a .webm video and JSON telemetry. Watch the video and check that the interaction and final result are visible. Keep generated recordings out of Git by adding this entry to .gitignore:

.gitignoregitignore
/tests/Browser/Videos/

Add CI publishing#

Continue with Recording Pest browser tests in GitHub Actions. It covers selecting tests, recording the PR commit and publishing with GitHub Actions identity. You do not need an upload token.

Troubleshooting#

  • Composer cannot find the recorder: check that the VCS repository command completed and that Composer can access diff-stage/recorder on GitHub.
  • Unsupported Browser version: use Browser 5.1.2 with Pest 5, or Browser 4.3.1 with Pest 4. Resolve the dependency constraint before recording again.
  • Playwright or Chromium is missing: install the Playwright version for your Browser package, then install Chromium. Browser 5.1.2 uses Playwright 1.63.0.
  • Your repository is missing: check the active Diff Stage team and the GitHub App’s selected repositories. Ask the team owner or admin to reconnect if necessary.

Related guides

Show your reviewers what changed

Add the recorder to your test suite, and your next pull request gets a video.

Create an accountRecorder on GitHub