flvx/tests/e2e/README.md

FLVX E2E Tests

End-to-end testing suite for FLVX Panel using Playwright and pytest.

Structure

tests/e2e/
├── conftest.py          # Pytest configuration and fixtures
├── pyproject.toml       # Python project configuration
├── with_server.py       # Server lifecycle manager
├── pages/               # Page Object Models
│   └── __init__.py
├── fixtures/            # Test fixtures and helpers
│   └── __init__.py
├── utils/               # Utility modules
│   ├── __init__.py
│   └── api_client.py    # Backend API client
├── test_auth.py         # Authentication tests
├── test_api.py          # API endpoint tests
├── test_dashboard.py    # Dashboard UI tests
└── test_user_ui.py      # User management UI tests

Prerequisites

• Python 3.11+
• Go 1.24+ (for backend)
• Node.js 18+ (for frontend)

Setup

# Create virtual environment
cd tests/e2e
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies
pip install -e ".[dev]"

# Install Playwright browsers
playwright install chromium

Running Tests

Quick Start

# Run all tests (starts servers automatically)
python with_server.py -- pytest -v

# Run specific test file
python with_server.py -- pytest test_auth.py -v

# Run with markers
python with_server.py -- pytest -m "auth" -v
python with_server.py -- pytest -m "api" -v
python with_server.py -- pytest -m "e2e" -v

Manual Server Management

If servers are already running:

# Set environment variables
export E2E_BACKEND_PORT=6365
export E2E_FRONTEND_PORT=3000

# Run tests directly
pytest -v

Custom Server Configuration

# Custom ports
python with_server.py --backend-port 8080 --frontend-port 5173 -- pytest -v

# Custom server commands
python with_server.py \
  --server "make run" --port 6365 --cwd go-backend \
  --server "pnpm run dev" --port 3000 --cwd vite-frontend \
  -- pytest -v

Test Markers

Marker	Description
@e2e	Full end-to-end test with browser
@api	API-only test, no browser required
@auth	Test requires authentication
@slow	Slow running test (>5s)

Writing Tests

API Tests

import pytest
from utils.api_client import APIClient

@pytest.mark.api
class TestMyAPI:
    def test_something(self, authenticated_api: APIClient):
        response = authenticated_api.post("/some/endpoint")
        assert response["code"] == 0

Browser Tests

import pytest
from playwright.sync_api import Page
from pages import LoginPage

@pytest.mark.e2e
class TestMyFeature:
    def test_something(self, page: Page, frontend_url: str):
        login_page = LoginPage(page, frontend_url)
        login_page.goto()
        # ...

Page Objects

Located in pages/__init__.py:

• LoginPage - Login form handling
• DashboardPage - Dashboard interactions
• UserPage - User management
• NodePage - Node management
• TunnelPage - Tunnel management
• ForwardPage - Forward management
• ConfigPage - Configuration

Fixtures

Key fixtures in conftest.py:

• server_info - Server configuration
• backend_url / frontend_url - Base URLs
• page - Fresh browser page
• authenticated_page - Page with logged-in session
• api_client - API client instance
• authenticated_api - Authenticated API client
• auth_token - JWT token string

Debugging

# Run with visible browser
pytest -v --headed

# Run specific test with debug output
pytest test_auth.py::TestAuthentication::test_login_with_valid_credentials -v -s

# Generate HTML report
pytest -v --html=report.html --self-contained-html

CI Integration

# Example GitHub Actions
- name: Run E2E tests
  run: |
    cd tests/e2e
    pip install -e ".[dev]"
    playwright install chromium
    python with_server.py -- pytest -v --junit-xml=test-results.xml