Skip to main content

​
Overview

The FE Monorepo uses different testing frameworks for each application type:
  • SPA & Web: Playwright for browser-based E2E testing
  • Expo: Maestro for mobile E2E testing

​
SPA Testing (Playwright)

The SPA uses Playwright 1.58.2 for end-to-end testing.

​
Setup

1

Install Playwright Browsers

Install Chromium browser for testing:
bun spa test:install
2

Ensure Environment File Exists

Make sure apps/spa/.env.dev exists with the required environment variables.

​
Running Tests

bun spa test
The test script automatically loads environment variables from .env.dev using dotenvx.

​
Test Configuration

Playwright tests for SPA use the following configuration:
  • Browser: Chromium only (for CI efficiency)
  • Sharding: 4 shards in CI for parallel execution
  • Reports: HTML reports stored in apps/spa/playwright-report
  • Environment: Development mode with .env.dev

​
CI Integration

The CI workflow runs SPA tests in parallel across 4 shards:
.github/workflows/ci.yml
strategy:
  fail-fast: false
  matrix:
    shardIndex: [1, 2, 3, 4]
    shardTotal: [4]
Tests can be skipped by including e2e skip or skip e2e in the commit message.

​
Web Testing (Playwright)

The Web app also uses Playwright 1.58.2 for end-to-end testing.

​
Setup

1

Install Playwright Browsers

Install Chromium browser for testing:
bun web test:install
2

Ensure Environment File Exists

Make sure apps/web/.env.dev exists with database and auth configuration.
3

Start Database

Ensure PostgreSQL is running for tests that require database access.

​
Running Tests

bun web test
The Web E2E tests are currently commented out in CI due to the need to mock the Better Auth API on the server-side.

​
Test Configuration

Playwright tests for Web use similar configuration to SPA:
  • Browser: Chromium only
  • Sharding: 4 shards for parallel execution
  • Reports: HTML reports stored in apps/web/playwright-report
  • Environment: Development mode with .env.dev

​
Expo Testing (Maestro)

The Expo app uses Maestro for mobile end-to-end testing.

​
Prerequisites

1

Install Maestro CLI

Follow the Maestro installation guide to install the CLI.
2

Build Development App

Create a development build and install it on your device/simulator:
bun expo build:android:dev:local
3

Start App

Launch the app on your device/simulator:
bun expo dev
As of May 2025, Maestro does not support physical iOS devices. Use iOS Simulator for testing.

​
Running Tests

bun expo test:dev
Maestro Studio opens an interactive UI at http://localhost:9999/interact to help write and debug test flows.

​
Test Flow Configuration

Maestro tests use environment variables to target the correct app variant: 
maestro test \
  -e MAESTRO_APP_ID=com.rifandani.expoapp.development \
  -e IS_DEV=true \
  .maestro/flows
Don’t run bun expo test:ui (Maestro Studio) and bun expo test:dev simultaneously. This will cause the error: “Unable to launch app”.

​
Maestro Studio

Maestro Studio is a visual tool for writing and debugging test flows:
1

Start Maestro Studio

bun expo test:ui
2

Open in Browser

Navigate to http://localhost:9999/interact
3

Write Test Flows

Use the visual interface to:
  • Interact with the app
  • Record interactions
  • Debug test flows
  • Generate YAML flow definitions

​
Upgrading Test Dependencies

​
Playwright

When upgrading Playwright to a new MINOR version:
1

Update Package Version

Update @playwright/test in the respective package.json
2

Install Browsers

Install the new version of Chromium:
bun web test:install  # or bun spa test:install
3

Run Tests

Verify tests still pass:
bun web test  # or bun spa test

​
Maestro

Maestro CLI is installed globally and managed separately: 
# Update Maestro CLI
maestro update

​
CI/CD Considerations

​
GitHub Actions

The monorepo uses GitHub Actions for running Playwright tests:
  • Parallel Execution: Tests run in 4 parallel shards
  • Artifact Upload: Test reports are saved for 7 days
  • Environment: Uses dev environment secrets
  • Skip Option: Add e2e skip to commit message to skip tests

​
Maestro in CI

Maestro tests cannot run on regular CI platforms like GitHub Actions because they require a physical device or simulator. Consider using Maestro Cloud for CI testing.

​
Performance Tips

Playwright:
  • Use --shard option to parallelize tests in CI
  • Run tests in headless mode by default
  • Only install Chromium (not all browsers) for faster setup
Maestro:
  • Keep test flows focused and concise
  • Use Maestro Studio for faster debugging
  • Test on development builds first before production

​
Troubleshooting

​
Playwright Issues

Tests fail to start:
  1. Ensure browsers are installed: bun spa test:install
  2. Check that .env.dev file exists
  3. Verify the development server isn’t already running
Flaky tests:
  1. Add proper wait conditions
  2. Use test.ui mode to debug
  3. Check network conditions and API responses

​
Maestro Issues

Unable to launch app:
  1. Ensure only one Maestro process is running
  2. Verify the app is installed on the device/simulator
  3. Check the MAESTRO_APP_ID environment variable matches your build
iOS Simulator not detected:
  1. Ensure a simulator is booted: xcrun simctl list devices | grep Booted
  2. Boot a simulator from Xcode before running tests

​
Quick Reference

TaskSPAWebExpo
Install test toolsbun spa test:installbun web test:installInstall Maestro CLI
Run testsbun spa testbun web testbun expo test:dev
Interactive modebun spa test:uibun web test:uibun expo test:ui
View reportbun spa test:reportbun web test:reportN/A
FrameworkPlaywright 1.58.2Playwright 1.58.2Maestro

Build docs developers (and LLMs) love

Get started for freeTalk to us