PEST 4 Browser Testing with Spin?

[akulmehta]

PEST 4 introduces some amazing browser testing capabilities. I have tried installing it Anyone have any suggestions how to integrate PEST browser testing with a project which uses Spin?

[akulmehta]

OK. After a few hours of troubleshooting, I got it to work. So here is a guide on how to do it.

Note I haven't tested this with CI as yet.

Setting Up Pest 4 Browser Testing with Playwright in Laravel + ServerSideUp Spin

This guide documents the complete setup process for implementing Pest 4's browser testing functionality using Playwright in a Laravel application running with ServerSideUp's Spin Docker environment.

Overview

This setup enables browser testing using:

• Pest 4 - Modern PHP testing framework with browser testing capabilities
• Playwright - Cross-browser automation library
• ServerSideUp Spin - Docker-based Laravel development environment

Prerequisites

• Laravel application running with ServerSideUp Spin
• Docker and Docker Compose installed
• Node.js support in your Docker environment

Step 1: Update Docker Configuration

Dockerfile Changes

The key changes needed in your Dockerfile:

1. Switch from Alpine to Debian-based image (required for Playwright dependencies):

   # Before
   FROM serversideup/php:8.4-fpm-nginx-alpine AS base
   
   # After  
   FROM serversideup/php:8.4-fpm-nginx AS base

2. Add Node.js installation and Playwright setup:

   USER root
   
   # Install Node.js and npm
   RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
       apt-get install -y nodejs
   
   RUN install-php-extensions bcmath gd imagick intl pcov sockets # sockets is required to be added
   
   # Install Playwright
   RUN npm install playwright@latest
   RUN npx playwright install --with-deps
   RUN npx playwright install chromium # add any other browsers you may want to test here

3. Add CI/testing dependencies (in the CI stage):

   # Install additional dependencies for CI/testing
   RUN apt-get update && apt-get install -y git

Why These Changes?

• Alpine → Debian: Playwright requires glibc which is not available in Alpine Linux
• Node.js: Required for Playwright installation and browser management
• --with-deps: Installs system dependencies needed by browsers
• Chromium: Specific browser installation for consistent testing environment
• sockets extension: Required for Pest's browser testing communication

After making these changes, rebuild your Docker containers:

spin build
spin up -d

Step 2: Update PHP Dependencies

Update your composer.json:

{
    "require-dev": {
        "pestphp/pest": "^4.0",
        "pestphp/pest-plugin-browser": "^4.1",
        "pestphp/pest-plugin-laravel": "^4.0"
    }
}

Install the updated dependencies:

spin exec php composer update

Step 3: Add Node.js Dependencies

Update your package.json:

{
    "dependencies": {
        "playwright": "^1.55.0"
    }
}

Install Node dependencies:

spin run node npm install

Step 4: Create and Run Browser Tests

Execute your browser tests using Spin:

spin exec php ./vendor/bin/pest

Or run specific tests:

spin exec php ./vendor/bin/pest --filter=BrowseRouteTest

Troubleshooting

Common Issues

1. Alpine Linux Issues: If you see glibc errors, ensure you're using the Debian-based image, not Alpine
2. Node.js Not Found: Verify Node.js installation in your Dockerfile
3. Browser Dependencies Missing: Ensure --with-deps flag is used with Playwright installation
4. Permission Issues: Browser tests run as www-data user in the container

Debugging Commands

# Check Playwright installation
spin exec php npx playwright --version

# Verify Node.js in container
spin exec php node --version

# Check if browsers are installed
spin exec php npx playwright install --dry-run

[jaydrogers]

Thank you so much for publishing your solution! 🙏

[akulmehta]

This might be a bit difficult as I am not sure how (and if) PEST can communicate with playwright on a separate docker container. An alternative would be to have a dedicated pest-browser-testing container which combines both. Thoughts?

[jaydrogers]

That could be good. As long as you're doing it in your Development and/or CI stage in the Dockerfile, it should work. For example, I would place that here in Benchkit if I needed it: https://github.com/serversideup/benchkit-laravel/blob/15add37d0b9eba09c881932b378d69e7747ee8da/Dockerfile#L88-L112

That way you're not deploying Node with PHP in Production (that would increase your attack surface area) 🤓

[akulmehta]

@jaydrogers are there any real-world downsides to using the Debian flavor of the docker php compared to the Alpine? Just wondering cause I would like my tests to run in the same Linux environment as what I would use in production.

[jaydrogers]

The main reason why Alpine is used over Debian is image size, but it's pretty negligible as of recent.

Some use Alpine for a smaller attack surface (since it has less packages), but Debian is highly trusted and secure.

In your case, I would use Debian across the board 💯

[akulmehta]

Thanks

[akulmehta]

Update: Running separate testing container and CI

Based on feedback on my previous post about increased attack surface area by having PHP and Node in the container which is used in production, I decided to create a separate testing container. Also I got it to work with CI as described below.

Would love feedback — especially if anyone has integrated this or similar setup into a CI pipeline with Spin.

Here is what I did now:

Dockerfile

I created a specific image for the php-testing container:

############################################
# Testing image with Browser Testing Support
############################################

FROM serversideup/php:8.4-fpm-nginx AS php-testing

# Accept same build args as development stage
ARG USER_ID
ARG GROUP_ID

USER root

# Install Node.js 20.x (required for Playwright)
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs git

# Install PHP extensions (including sockets for Pest browser testing)
RUN install-php-extensions bcmath gd imagick intl exif sockets

# Set working directory
WORKDIR /var/www/html

# Configure www-data permissions
RUN docker-php-serversideup-set-id www-data $USER_ID:$GROUP_ID && \
    docker-php-serversideup-set-file-permissions --owner $USER_ID:$GROUP_ID --service nginx

# Copy package.json files first for caching
COPY --chown=$USER_ID:$GROUP_ID package*.json ./

# Install npm dependencies as www-data
USER www-data
RUN npm install

# Switch to root to install system-level Playwright deps
USER root
RUN npm install -g playwright@latest
RUN npx playwright install-deps chromium

# Switch back to www-data for local Playwright browser installation
USER www-data
RUN npx playwright install chromium

# Switch back to root for cleanup and permissions
USER root
RUN chown -R $USER_ID:$GROUP_ID /var/www/html/node_modules
RUN chown -R $USER_ID:$GROUP_ID /var/www/.cache

# Create temp directories for Pest browser testing
RUN mkdir -p /var/www/html/vendor/pestphp/pest/.temp && \
    mkdir -p /var/www/html/vendor/pestphp/pest-plugin-browser/.temp && \
    chown -R $USER_ID:$GROUP_ID /var/www/html/vendor/pestphp/pest/.temp && \
    chown -R $USER_ID:$GROUP_ID /var/www/html/vendor/pestphp/pest-plugin-browser/.temp

# Add entrypoint scripts
COPY --chmod=755 ./entrypoint.d/ /etc/entrypoint.d/

# Drop privileges back to www-data
USER www-data

docker-compose.dev.yml

I added the following service definition:

  # Dedicated PHP testing container with Node.js and Playwright for browser testing
  php-testing:
    build:
      target: php-testing
      args:
        USER_ID: ${SPIN_USER_ID}
        GROUP_ID: ${SPIN_GROUP_ID}
    stop_signal: SIGTERM
    volumes:
      - .:/var/www/html/
    networks:
      - development
    depends_on:
      postgrestest:
        condition: service_started
    environment:
      # Base testing environment
      - APP_ENV=testing
      # DB config handled via phpunit.xml / phpunit.pgsql.xml

Rebuild containers:

Run:

spin build
spin up -d

Run tests in php-testing container

spin exec php-testing ./vendor/bin/pest tests/Browser

Technically you can use this container for all your tests.

For CI I added the following to my workflows pull-request.yml

  browser-tests-sqlite:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: "8.4"

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: lts/*

      - name: Copy .env
        run: php -r "file_exists('.env') || copy('.env.example', '.env');"

      - name: Install Composer Dependencies
        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist

      - name: Install NPM Dependencies
        run: npm ci

      - name: Install Playwright Browsers
        run: npx playwright install --with-deps chromium

      - name: Build Assets
        run: npm run build

      - name: Generate key
        run: php artisan key:generate

      - name: Directory Permissions
        run: chmod -R 777 storage bootstrap/cache

      - name: Create Database
        run: |
          mkdir -p database
          touch database/database.sqlite

      - name: Execute Browser Tests (SQLite)
        env:
          DB_CONNECTION: sqlite
          DB_DATABASE: database/database.sqlite
          DB_FOREIGN_KEYS: true
          APP_ENV: testing
        run: ./vendor/bin/pest tests/Browser --compact