End-to-end tests for WebSSH2, covering authentication, WebSocket connections, terminal functionality, and performance.

1. Node.js - Version 22 or higher
2. Docker - Required for the test SSH server (automatically managed)
3. Playwright - Install with npm run e2e:setup

tests/playwright/
├── constants.js                     # Shared test configuration
├── debug/                           # Debug and diagnostic tests
│   ├── debug-event-flow.spec.ts
│   ├── debug-post-auth-flow.spec.ts
│   └── debug-test.spec.js
├── performance/                     # Performance tests (archived for migration)
│   ├── PERFORMANCE_TESTS.md        # Performance test specifications
│   ├── websocket-latency.test.js.archived
│   └── websocket-performance.test.js.archived
├── e2e-term-size-replay.spec.ts    # Terminal size and replay tests
├── websocket-async-auth.test.js    # Async WebSocket authentication
├── websocket-auth.test.js          # WebSocket authentication scenarios
└── websocket-basic.test.js         # Basic WebSocket functionality

# Install Playwright and dependencies
npm run e2e:setup

# Run all E2E tests (starts SSH container automatically)
npm run test:e2e

# Run with debug output
npm run test:e2e:debug

# Run specific test file
npx playwright test tests/playwright/websocket-auth.test.js

# Run tests in UI mode
npx playwright test --ui

# Run tests in headed mode (see browser)
npx playwright test --headed

• npm run test:e2e - Run all Playwright tests with SSH server
• npm run test:e2e:debug - Run tests with debug output
• npm run e2e:setup - Install Playwright with dependencies
• npm run test - Run unit tests
• npm run test:all - Run all tests (unit + integration)

Tests are configured in playwright.config.ts:

• Test directory: ./tests/playwright
• Timeout: 60 seconds per test
• Workers: 1 (prevents SSH connection conflicts)
• Browser: Chromium
• Base URL: http://localhost:2288
• Auto-start: WebSSH2 server on port 2288
• SSH container: Automatically started when ENABLE_E2E_SSH=1

• ENABLE_E2E_SSH=1 - Enables SSH container for E2E tests (automatically managed)
• DEBUG=webssh2:* - Enable debug logging
• E2E_DEBUG=webssh2:* - Enable debug logging for E2E tests

• Interactive authentication (valid/invalid credentials)
• Basic Auth scenarios
• HTTP POST authentication flow
• Connection error handling
• Session management

• Async connection establishment
• Auto-connect with Basic Auth
• Connection resilience
• Message flow validation

• Terminal size and resize handling
• TERM environment variable validation
• Replay functionality
• Command execution

Performance tests have been temporarily archived during the TypeScript migration. See performance/PERFORMANCE_TESTS.md for detailed specifications and future implementation plans.

Key test categories:

• Connection establishment latency
• Large data transfer handling
• Rapid command execution
• Long-term connection stability
• Terminal resize performance
• Concurrent connection scaling

• Event flow analysis
• HTTP POST authentication flow
• Connection diagnostics

Default credentials for the test SSH server:

• Host: localhost
• Port: 2244 (SSH container) or 2289 (manual Docker)
• Username: testuser
• Password: testpassword

# View HTML report after test run
npx playwright show-report

# View test traces for debugging
npx playwright show-trace test-results/*/trace.zip

# Test artifacts location:
# - playwright-report/     # HTML report
# - test-results/         # Screenshots, videos, traces

# Debug specific test
npx playwright test websocket-auth.test.js --debug

# Run with verbose output
npm run test:e2e:debug

• Screenshots: test-results/*/screenshot.png
• Videos: test-results/*/video.webm
• Traces: test-results/*/trace.zip

If you need to run tests with a manual SSH server:

# Start test SSH container
docker run --rm -d \
  -p 2289:22 \
  -e SSH_USER=testuser \
  -e SSH_PASSWORD=testpassword \
  ghcr.io/billchurch/ssh_test:alpine

# Run tests against manual server
SSH_PORT=2289 npx playwright test

Tests run automatically in CI:

• On push to main branches
• On pull requests
• Multiple Node.js versions tested
• Test reports uploaded as artifacts

# Check what's using the port
lsof -i :2288

# Kill the process if needed
pkill -f "node.*webssh2"

# Check if container is running
docker ps | grep ssh

# View container logs
docker logs $(docker ps -q --filter ancestor=ghcr.io/billchurch/ssh_test:alpine)

# Remove stale containers
docker rm -f $(docker ps -aq --filter name=webssh2)

• Ensure server starts with WebSocket support
• Check browser console for errors
• Verify firewall/proxy settings

• Increase timeout in playwright.config.ts
• Check server logs: DEBUG=webssh2:* npm run test:e2e:debug
• Ensure Docker is running

import { test, expect } from '@playwright/test'
import { BASE_URL, SSH_HOST, SSH_PORT, USERNAME, PASSWORD, TIMEOUTS } from './constants.js'

test.describe('Feature Name', () => {
  test('should do something', async ({ page }) => {
    await page.goto(`${BASE_URL}/ssh`)
    
    // Your test logic here
    
    await expect(page.locator('text=Connected')).toBeVisible()
  })
})

1. Use constants from constants.js
2. Add appropriate timeouts for operations
3. Include meaningful assertions
4. Clean up resources in test teardown
5. Use descriptive test names
6. Group related tests with test.describe

When adding new tests:

1. Follow existing test patterns
2. Update this README if adding new test categories
3. Ensure tests pass locally before pushing
4. Add debug tests to debug/ directory
5. Use TypeScript for new test files when possible