Configuration

Pest Plugin Bridge uses the Bridge class for programmatic configuration of external frontend URLs.

Global Configuration

Configure in your tests/Pest.php file:

<?php

use TestFlowLabs\PestPluginBridge\Bridge;

// Set the default frontend URL
Bridge::setDefault('http://localhost:5173');

This is the recommended approach for single-frontend projects.

Automatic Server Management

The plugin can automatically start and stop your frontend server:

<?php
// tests/Pest.php

use TestFlowLabs\PestPluginBridge\Bridge;
use Tests\TestCase;

// Configure frontend with automatic server management
Bridge::setDefault('http://localhost:3000')
    ->serve('npm run dev', cwd: '../frontend');

pest()->extends(TestCase::class)->in('Browser');

How It Works

1. Lazy Start: Server starts automatically on the first bridge() call
2. API URL Injection: Laravel API URL is injected via environment variables:
   • API_URL, VITE_API_URL, NUXT_PUBLIC_API_BASE, NEXT_PUBLIC_API_URL, REACT_APP_API_URL
3. Ready Detection: Waits for server output to match the pattern before continuing
4. Auto Stop: Server stops automatically when tests complete (via shutdown handler)

Configuration Options

Method	Description
->serve(string $command, ?string $cwd = null)	Command to start the server
->readyWhen(string $pattern)	Regex pattern to detect server ready (optional, default covers Nuxt, Vite, Next.js, CRA, Angular)

readyWhen() is Optional

The default pattern (ready|localhost|started|listening|compiled|http://|https://) covers most frontend dev servers. Only use readyWhen() if your server has a unique output format.

Multiple Frontends with Auto-Start

Bridge::setDefault('http://localhost:3000')
    ->serve('npm run dev', cwd: '../customer-portal');

Bridge::frontend('admin', 'http://localhost:3001')
    ->serve('npm run dev', cwd: '../admin-panel');

URL Validation

The plugin validates URLs using PHP's filter_var() with FILTER_VALIDATE_URL. Invalid URLs throw an InvalidArgumentException:

// Valid URLs
Bridge::setDefault('http://localhost:5173');     // ✅
Bridge::setDefault('https://staging.app.com');  // ✅
Bridge::setDefault('http://192.168.1.100:3000'); // ✅

// Invalid URLs
Bridge::setDefault('localhost:5173');           // ❌ Missing scheme
Bridge::setDefault('not-a-url');                // ❌ Invalid format
Bridge::setDefault('');                         // ❌ Empty string

Checking Configuration

You can check if a frontend is configured before running tests:

use TestFlowLabs\PestPluginBridge\Bridge;

if (!Bridge::has()) {
    throw new RuntimeException('Default frontend not configured');
}

// Check named frontend
if (!Bridge::has('admin')) {
    throw new RuntimeException('Admin frontend not configured');
}

Resetting Configuration

The plugin automatically resets configuration when tests complete via a shutdown handler. Manual reset is rarely needed, but available:

// Manual reset (rarely needed)
Bridge::reset();

Multiple Frontends

For projects with multiple frontends (micro-frontends, admin panels, customer portals), register named frontends:

<?php
// tests/Pest.php

use TestFlowLabs\PestPluginBridge\Bridge;

Bridge::setDefault('http://localhost:3000');           // Customer portal
Bridge::frontend('admin', 'http://localhost:3001');    // Admin dashboard
Bridge::frontend('analytics', 'http://localhost:3002'); // Analytics panel

Then use them in your tests:

<?php
// tests/Browser/MultiFrontendTest.php

test('customer can view products', function () {
    // Uses default frontend (localhost:3000)
    $this->bridge('/products')
        ->assertSee('Product Catalog');
});

test('customer can add to cart', function () {
    // Uses default frontend (localhost:3000)
    $this->bridge('/products/1')
        ->click('[data-testid="add-to-cart"]')
        ->assertVisible('[data-testid="cart-badge"]');
});

test('admin can view all users', function () {
    // Uses admin frontend (localhost:3001)
    $this->bridge('/users', 'admin')
        ->assertSee('User Management');
});

test('admin can create user', function () {
    // Uses admin frontend (localhost:3001)
    $this->bridge('/users/create', 'admin')
        ->fill('[data-testid="name-input"]', 'New User')
        ->click('[data-testid="save-button"]')
        ->assertSee('User created');
});

test('shows revenue metrics', function () {
    // Uses analytics frontend (localhost:3002)
    $this->bridge('/analytics', 'analytics')
        ->assertVisible('[data-testid="revenue-chart"]');
});

Named Frontends

Named frontends are registered once in tests/Pest.php and available in all test files. No need to repeat configuration in each file.