158 lines
3.8 KiB
Markdown
158 lines
3.8 KiB
Markdown
# Paskia E2E Tests
|
|
|
|
End-to-end tests for Paskia using [Playwright](https://playwright.dev/) with Chrome's **Virtual Authenticator**.
|
|
|
|
## Overview
|
|
|
|
These tests exercise the complete WebAuthn/passkey authentication flow without requiring physical hardware. Chrome's DevTools Protocol provides a virtual authenticator that can:
|
|
|
|
- Generate passkey credentials
|
|
- Sign authentication challenges
|
|
- Store resident keys (discoverable credentials)
|
|
- Simulate user verification (biometrics/PIN)
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 18+
|
|
- Python with `uv` (for running the backend server)
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
cd e2e
|
|
npm install
|
|
npm run install:browsers
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
### Basic Test Run
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
This will:
|
|
1. Start a fresh Paskia server with a test database
|
|
2. Run all E2E tests against it
|
|
3. Clean up the server when done
|
|
|
|
### Interactive Mode
|
|
|
|
```bash
|
|
npm run test:ui
|
|
```
|
|
|
|
Opens Playwright's UI mode for interactive test debugging.
|
|
|
|
### Headed Mode
|
|
|
|
```bash
|
|
npm run test:headed
|
|
```
|
|
|
|
Runs tests with a visible browser window.
|
|
|
|
### Debug Mode
|
|
|
|
```bash
|
|
npm run test:debug
|
|
```
|
|
|
|
Runs tests with Playwright Inspector for step-by-step debugging.
|
|
|
|
## Test Structure
|
|
|
|
```
|
|
e2e/
|
|
├── playwright.config.ts # Playwright configuration
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── test-data/ # Test database (created at runtime)
|
|
│ └── test.sqlite
|
|
└── tests/
|
|
├── global-setup.ts # Creates fresh DB, captures reset token
|
|
├── global-teardown.ts # Cleanup
|
|
├── passkey.spec.ts # Main E2E tests
|
|
└── fixtures/
|
|
├── virtual-authenticator.ts # Virtual authenticator setup
|
|
└── passkey-helpers.ts # WebSocket helpers
|
|
```
|
|
|
|
## What's Tested
|
|
|
|
### Registration Flow
|
|
- Bootstrap admin user registration via reset token
|
|
- WebSocket challenge-response with virtual authenticator
|
|
- Session token creation and validation
|
|
|
|
### Authentication Flow
|
|
- Passkey authentication via WebSocket
|
|
- Credential verification
|
|
- Session management
|
|
|
|
### Session Management
|
|
- Token validation (`/auth/api/validate`)
|
|
- User info retrieval (`/auth/api/user-info`)
|
|
- Logout (`/auth/api/logout`)
|
|
- Invalid/missing token rejection
|
|
|
|
## How Virtual Authenticator Works
|
|
|
|
The tests use Chrome DevTools Protocol (CDP) to create a virtual authenticator:
|
|
|
|
```typescript
|
|
const cdpSession = await page.context().newCDPSession(page)
|
|
await cdpSession.send('WebAuthn.enable')
|
|
await cdpSession.send('WebAuthn.addVirtualAuthenticator', {
|
|
options: {
|
|
protocol: 'ctap2',
|
|
transport: 'internal',
|
|
hasResidentKey: true,
|
|
hasUserVerification: true,
|
|
isUserVerified: true,
|
|
automaticPresenceSimulation: true,
|
|
},
|
|
})
|
|
```
|
|
|
|
This creates an in-browser authenticator that:
|
|
- Automatically responds to WebAuthn prompts
|
|
- Stores credentials persistently during the test session
|
|
- Simulates user verification without actual biometric input
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `BASE_URL` | Server URL | `http://localhost:4401` |
|
|
| `CI` | CI environment flag | - |
|
|
| `CLEANUP_TEST_DB` | Remove test DB after run | `false` |
|
|
|
|
## Limitations
|
|
|
|
1. **Chromium only**: Virtual authenticator is a Chrome DevTools feature
|
|
2. **No cross-origin**: Tests run on localhost; production-like origins need additional setup
|
|
3. **Single user per run**: Bootstrap creates one admin user; additional users need admin API
|
|
|
|
## Debugging Tips
|
|
|
|
1. **Check test database**: `e2e/test-data/test.sqlite` persists after tests
|
|
2. **View server output**: Global setup echoes server bootstrap to console
|
|
3. **Use trace viewer**: `npx playwright show-trace` on failure traces
|
|
|
|
## CI Integration
|
|
|
|
The tests are designed for CI environments:
|
|
|
|
```yaml
|
|
- name: Run E2E Tests
|
|
run: |
|
|
cd e2e
|
|
npm ci
|
|
npm run install:browsers
|
|
npm test
|
|
env:
|
|
CI: true
|
|
```
|