Browser testing

Laravolt v7 uses Pest Browser and Playwright to test critical UI flows in a real browser.

Unit and feature tests prove the backend works. Browser tests prove the product surface works: pages render, forms are usable, validation appears, menus are visible, and role-protected actions behave the way users expect.

What to test in a browser

Do not move your whole test suite into the browser. Use browser tests for flows where the HTML, JavaScript, CSS, or Livewire interaction matters.

Good browser test candidates:

• login page smoke test
• navigation and sidebar visibility
• create/edit form rendering
• client-side validation attributes
• input masking behaviour
• Livewire table search/filter/sort
• permission-dependent buttons
• file upload preview flows
• approval workflow happy paths

Keep business rules in feature/unit tests. Keep browser tests focused on the interface contract.

Install dependencies

Laravolt v7 includes Pest Browser support in the platform setup. A project that runs browser tests also needs Playwright in the application root.

composer require --dev pestphp/pest-plugin-browser
npm install --save-dev playwright@1.59.1
npx playwright install chromium

The test directory

Put browser tests in tests/Browser:

tests/
  Browser/
    LoginTest.php
    ProductWorkflowTest.php

A small smoke test is better than a large brittle flow:

use function Pest\Laravel\get;
it('renders the login page', function () {
    $page = visit('/auth/login');
    $page->assertSee('Login')
        ->assertPresent('input[name="email"]')
        ->assertPresent('input[name="password"]');
});

The current skeleton redirects / to /auth/login and names the login route auth::login.show.

Running browser tests

Run browser tests through Pest Browser or the browser command configured by your application:

php artisan test --filter=Browser
# or, when using Pest Browser directly
vendor/bin/pest tests/Browser

Keep the exact command in your project README or CI workflow so local and CI runs use the same browser driver.

CI setup

Browser tests need Node and Playwright installed before the Pest command runs.

- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version: 22
- name: Install Playwright
  run: |
    npm install --save-dev playwright@1.59.1
    npx playwright install --with-deps chromium
- name: Run browser tests
  run: vendor/bin/pest tests/Browser

For faster CI, run browser tests after unit/feature tests pass. Browser failures are usually more expensive to debug, so fail fast on PHP syntax, static analysis, and feature tests first.

Writing stable browser tests

Prefer tests that check user-visible contracts:

it('shows validation feedback when required fields are empty', function () {
    $page = visit('/products/create');
    $page->press('Save product')
        ->assertSee('The product name field is required');
});

Avoid tests that depend on implementation details:

• generated IDs that can change
• CSS classes unrelated to behaviour
• exact animation timing
• third-party network calls
• seeded data that another test mutates

Browser testing and AI-assisted development

Browser tests are useful guardrails for coding agents. After asking an agent to change a form, table, menu, or workflow, ask it to update the matching browser test.

A good task prompt:

Update the Product create form to add SKU input masking.
Use PrelineForm. Update the browser test to assert the SKU field is present
and accepts the expected mask pattern. Run your browser test command if Playwright
is installed; otherwise explain the exact local setup needed.

Troubleshooting

Playwright is not installed

Install Playwright in the application root:

npm install --save-dev playwright@1.59.1
npx playwright install chromium

Browser tests pass locally but fail in CI

Check that CI installs browser dependencies with --with-deps and that the app key, database, queue, and asset build steps match your normal feature test environment.

Tests are flaky

Reduce the test scope. Browser tests should verify a small contract, not every detail of a workflow. Move business rule assertions back to feature tests.

What to read next

• Forms validation — server and client validation conventions.
• Input masking — browser-visible field behaviour worth testing.
• Access control — combine policy tests with browser smoke tests for protected UI.