browse

Browse — Playwright E2E Testing for SolanaOS Hub

Browser automation and end-to-end testing skill for the SolanaOS NanoHub, powered by Playwright.

Quick Start

# Install Playwright browsers
npx playwright install chromium

# Run E2E tests
bun run test:e2e

# Run with UI mode
npx playwright test --ui

# Generate tests interactively
npx playwright codegen https://seeker.solanaos.net

NanoHub Test Configuration

The NanoHub uses a dual config setup:

Playwright Config (playwright.config.ts)

Browser-based E2E tests against the built frontend.

import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  testMatch: /.*\.pw\.test\.ts/,
  timeout: 60_000,
  expect: { timeout: 10_000 },
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  use: {
    baseURL: process.env.PLAYWRIGHT_BASE_URL || 'http://127.0.0.1:4173',
    trace: 'retain-on-failure',
  },
  webServer: {
    command: 'bun run preview -- --host 127.0.0.1 --port 4173',
    url: 'http://127.0.0.1:4173',
    reuseExistingServer: !process.env.CI,
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
})

Vitest E2E Config (vitest.e2e.config.ts)

Node-based E2E tests for CLI and API validation (no browser needed).

bun vitest run -c vitest.e2e.config.ts

NanoHub Routes to Test

Route	Auth	What to verify
/	No	Landing page renders, navigation works
/launch	No	Boot sequence animation, CTA links
/mobile	No	Seeker mobile walkthrough renders
/skills	No	Skill cards load from Convex
/souls	No	Soul cards load from Convex
/ipfs	No	IPFS Hub page renders, wallet input works
/agents	No	Agent directory loads public agents
/dashboard	Yes	Wallet connect, agent factory, pairing
/upload	Yes	Skill publish flow with file upload
/settings	Yes	User preferences, agent config
/mining	No	BitAxe fleet dashboard renders
/strategy	No	Strategy builder loads
/create	Yes	Skill creator wizard
/auth/callback	No	GitHub OAuth redirect handling

Writing Hub Tests

Public Route Test

import { test, expect } from '@playwright/test'

test('IPFS Hub page loads', async ({ page }) => {
  await page.goto('/ipfs')
  await expect(page.locator('h1')).toContainText('Private IPFS')
  await expect(page.locator('.gallery-stat-card')).toHaveCount(4)
})

test('agent directory shows cards', async ({ page }) => {
  await page.goto('/agents')
  await expect(page.locator('h1')).toContainText('Registered')
  // Wait for Convex query
  await page.waitForSelector('.agent-card', { timeout: 10_000 })
})

test('skill search works', async ({ page }) => {
  await page.goto('/skills')
  await page.locator('input[type="search"]').fill('solanaos')
  await page.waitForSelector('.skill-card')
  await expect(page.locator('.skill-card')).toHaveCount.greaterThan(0)
})

Authenticated Route Test

import { test, expect } from '@playwright/test'

// Use storage state from auth setup
test.use({ storageState: 'e2e/.auth/user.json' })

test('dashboard loads for authenticated user', async ({ page }) => {
  await page.goto('/dashboard')
  await expect(page.locator('.dashboard-section')).toBeVisible()
})

Convex API Test (Vitest, no browser)

import { describe, expect, it } from 'vitest'

const CONVEX_URL = process.env.CONVEX_URL || 'https://artful-frog-940.convex.cloud'

describe('Convex IPFS API', () => {
  it('GET /api/v1/ipfs/files returns array', async () => {
    const res = await fetch(
      `${CONVEX_URL}/api/v1/ipfs/files?wallet=test`,
      { headers: { Accept: 'application/json' } }
    )
    expect(res.ok).toBe(true)
    const data = await res.json()
    expect(data).toHaveProperty('files')
    expect(Array.isArray(data.files)).toBe(true)
  })

  it('GET /api/v1/ipfs/stats returns stats object', async () => {
    const res = await fetch(
      `${CONVEX_URL}/api/v1/ipfs/stats?wallet=test`,
      { headers: { Accept: 'application/json' } }
    )
    expect(res.ok).toBe(true)
    const data = await res.json()
    expect(data.stats).toHaveProperty('totalFiles')
  })
})

Playwright Agents (AI-Driven Testing)

Playwright includes three built-in AI test agents.

Setup

npx playwright init-agents --loop=vscode

Planner

Explores the app and produces a Markdown test plan.

Input: "Generate a test plan for the IPFS Hub upload and recall flow"
Output: specs/ipfs-hub.md

The planner needs a seed test that sets up the environment:

// tests/seed.spec.ts
import { test } from '@playwright/test'

test('seed', async ({ page }) => {
  await page.goto('/')
})

Generator

Transforms Markdown plans into executable Playwright test files.

Input: specs/ipfs-hub.md
Output: tests/ipfs-hub/upload-file.spec.ts

Healer

Automatically repairs failing tests by:

1. Replaying failing steps
2. Inspecting current UI for equivalent elements
3. Patching locators, waits, or data
4. Re-running until pass or skip

Input: "Heal tests/ipfs-hub/upload-file.spec.ts"
Output: Passing test (or skipped with reason)

Configuration Reference

Top-Level Options

Option	Description
testDir	Directory with test files
testMatch	Glob/regex for test file matching
testIgnore	Glob/regex for files to skip
timeout	Per-test timeout (default: 30s)
retries	Retry count for flaky tests
workers	Parallel worker count
fullyParallel	Run all tests in parallel
forbidOnly	Fail if test.only found (CI)
reporter	Output format: list, html, json, dot
outputDir	Artifacts directory (screenshots, videos, traces)
globalSetup	Path to setup script (runs before all tests)
globalTeardown	Path to teardown script (runs after all tests)
webServer	Auto-start dev server before tests

use Options

Option	Description
baseURL	Base URL for page.goto('/')
storageState	Pre-populated auth state
trace	Trace capture: off, on, retain-on-failure, on-first-retry
screenshot	Screenshot capture: off, on, only-on-failure
video	Video recording: off, on, retain-on-failure
headless	Run without browser UI (default: true)
viewport	Browser viewport size
locale	User locale emulation
colorScheme	light or dark mode
geolocation	GPS coordinate emulation
permissions	Browser permission grants
offline	Simulate offline mode
proxy	HTTP proxy settings
extraHTTPHeaders	Headers sent with every request
actionTimeout	Timeout per action (click, fill, etc.)
testIdAttribute	Custom test ID attribute

Annotations

// Skip a test
test.skip('not ready', async ({ page }) => {})

// Mark as expected failure
test.fail('known bug', async ({ page }) => {})

// Mark as slow (3x timeout)
test.slow()

// Tag for filtering
test('login @smoke', async ({ page }) => {})
test('checkout', { tag: ['@e2e', '@slow'] }, async ({ page }) => {})

// Run tagged tests
// npx playwright test --grep @smoke
// npx playwright test --grep-invert @slow

CLI Commands

# Run all tests
npx playwright test

# Run specific file
npx playwright test e2e/ipfs-hub.pw.test.ts

# Run by title match
npx playwright test -g "IPFS Hub"

# Run with browser visible
npx playwright test --headed

# Debug mode (inspector + slow)
npx playwright test --debug

# Interactive UI mode
npx playwright test --ui

# Generate test code interactively
npx playwright codegen https://seeker.solanaos.net

# View last test report
npx playwright show-report

# View trace file
npx playwright show-trace test-results/trace.zip

# Only re-run failures
npx playwright test --last-failed

# Shard across CI workers
npx playwright test --shard=1/3

CI Integration

# .github/workflows/e2e.yml
name: E2E Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: npx playwright install --with-deps chromium
      - run: bun run build
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

NanoHub E2E Environment Variables

Variable	Description
PLAYWRIGHT_BASE_URL	Override base URL (skip local server)
PLAYWRIGHT_PORT	Override preview server port (default: 4173)
CLAWHUB_E2E_TOKEN	API token for authenticated CLI tests
CLAWDHUB_E2E_TOKEN	Alias for above
CLAWHUB_REGISTRY	Registry URL override
CLAWHUB_SITE	Site URL override
CI	Enables retries, single worker, forbidOnly