bede/tfm_ainventory
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
5618e9d9f8728d538aeb772c2a8b404230da7cd6
tfm_ainventory/frontend/e2e/README.md

7.1 KiB
Raw Blame History

E2E Test Suite - Playwright

Comprehensive end-to-end tests for aInventory using Playwright, covering all major user workflows.

Directory Structure

frontend/e2e/
├── workflows/              # Test scenarios (5 modular workflows)
│   ├── 1-login.spec.ts          # LDAP + local authentication
│   ├── 2-scan-adjust.spec.ts    # Barcode scanning & stock adjustment
│   ├── 3-ai-extraction.spec.ts  # AI-powered item onboarding
│   ├── 4-admin-settings.spec.ts # Admin dashboard configuration
│   └── 5-offline-sync.spec.ts   # Offline queue & sync recovery
├── fixtures/               # Shared test infrastructure
│   ├── test-data.ts             # Seed data, users, items
│   ├── db.ts                    # SQLite database setup/cleanup
│   ├── ldap.ts                  # OpenLDAP container management
│   └── auth.ts                  # Authentication helpers
├── utils/                  # Utility functions
│   ├── assertions.ts            # Custom Playwright matchers
│   ├── docker.ts                # Container orchestration
│   └── helpers.ts               # Navigation & DOM helpers
├── docker-compose.e2e.yml # Docker services template
├── playwright.config.ts    # Playwright configuration
└── README.md               # This file

Setup

Prerequisites

  • Node.js 20+
  • Docker & Docker Compose
  • Playwright installed: npm install

Installation

cd frontend

# Install Playwright
npm install

# Verify installation
npx playwright --version

Configuration

Edit playwright.config.ts to adjust:

  • baseURL: Application URL (default: http://localhost)
  • timeout: Test timeout (default: 30s)
  • retries: Retry on failure (default: 0 in dev, 2 in CI)
  • workers: Parallel test workers (default: 5)

Environment Variables:

BASE_URL=http://localhost:3000
SKIP_LDAP=false  # Skip LDAP tests if not configured
CI=false         # Set to true for CI environment

Running Tests

All Tests

npx playwright test

Specific Workflow

npx playwright test 1-login.spec.ts
npx playwright test 2-scan-adjust.spec.ts
npx playwright test 3-ai-extraction.spec.ts
npx playwright test 4-admin-settings.spec.ts
npx playwright test 5-offline-sync.spec.ts

With Browser UI

npx playwright test --ui

Debug Mode

npx playwright test --debug

Generate Report

npx playwright test
npx playwright show-report

Test Workflows

1. Login (1-login.spec.ts)

  • LDAP authentication
  • Local user login
  • Session persistence
  • Logout functionality
  • User identity display

Duration: ~30s | Tests: 14

2. Scan & Adjust (2-scan-adjust.spec.ts)

  • Scanner interface initialization
  • Barcode scanning
  • Item matching
  • Stock adjustment (check-in/check-out)
  • Quantity validation
  • Multiple consecutive scans

Duration: ~45s | Tests: 18

3. AI Extraction (3-ai-extraction.spec.ts)

  • AI onboarding wizard
  • Image capture
  • AI-powered extraction (Gemini/Claude)
  • Result validation
  • Manual field editing
  • Multi-item extraction

Duration: ~60s | Tests: 16

4. Admin Settings (4-admin-settings.spec.ts)

  • Admin dashboard access
  • User management (CRUD)
  • Database configuration
  • LDAP settings
  • AI provider selection
  • Category management

Duration: ~90s | Tests: 22

5. Offline Sync (5-offline-sync.spec.ts)

  • Offline mode detection
  • Operation queueing
  • Sync on reconnection
  • Duplicate prevention (UUID tracking)
  • Queue persistence (IndexedDB)
  • Sync history

Duration: ~120s | Tests: 14

Total: ~345s (~5.75 min) | Tests: 84

Docker Compose

E2E tests can run against Docker Compose services:

# Start services
docker-compose -f frontend/e2e/docker-compose.e2e.yml up -d

# Run tests
npx playwright test

# Stop services
docker-compose -f frontend/e2e/docker-compose.e2e.yml down

Test Data

Predefined users for testing:

  • LDAP: testuser1 / Password123!
  • Local (Admin): admin / AdminPassword123!
  • Local (User): testuser2 / UserPassword123!

Test items available in fixtures:

  • Widget A (barcode: 123456789)
  • Widget B (barcode: 987654321)
  • Capacitor Pack (barcode: 555666777)
  • Resistor Assortment (barcode: 111222333)

CI/CD Integration

For continuous integration:

# Run tests in CI mode
CI=true npx playwright test

# Generate JUnit report
npx playwright test --reporter=junit > test-results.xml

Troubleshooting

Tests Timing Out

  • Increase timeout in playwright.config.ts
  • Check backend service health: http://localhost:8906/health
  • Verify Docker containers are running

LDAP Tests Failing

  • Set SKIP_LDAP=true if LDAP unavailable
  • Check OpenLDAP container: docker ps | grep ldap
  • Verify LDAP server is healthy

Network Issues

  • Ensure Docker network bridge is active
  • Check firewall rules
  • Verify port availability (3000, 8906, 389)

Screenshot/Video Artifacts

  • Check test-results/ directory
  • Videos saved on test failure
  • Screenshots in failure mode

Development Tips

Writing New Tests

test('should do something', async ({ page }) => {
  // 1. Setup: navigate and authenticate
  await page.goto(BASE_URL);
  await auth.loginWithLocalUser(page, credentials, BASE_URL);

  // 2. Execute: perform user action
  await page.click('[data-testid="button"]');

  // 3. Assert: verify expected outcome
  await assertions.assertSuccessMessage(page);
});

Using Fixtures

import * as auth from '../fixtures/auth';
import * as db from '../fixtures/db';
import { TEST_ITEMS } from '../fixtures/test-data';

Custom Assertions

import * as assertions from '../utils/assertions';

await assertions.assertUserAuthenticated(page);
await assertions.assertStockAdjustmentVisible(page, itemName);

Helpers

import * as helpers from '../utils/helpers';

await helpers.fillField(page, selector, value);
await helpers.clickAndWait(page, selector, 'navigation');
const text = await helpers.getText(page, selector);

Performance Targets

  • Single workflow: <2 min
  • All workflows: <6 min
  • Parallel (5 workers): <2 min (CI mode)

Known Limitations

  1. jsdom Constraints: Video/canvas elements in jsdom don't fully simulate browser APIs
  2. AI Mocking: AI extraction tests use mocked responses for consistency
  3. LDAP Optional: LDAP tests skipped if service unavailable
  4. Offline Testing: NetworkError emulation may behave differently in real networks

Contributing

When adding new tests:

  1. Follow AAA pattern (Arrange, Act, Assert)
  2. Use [data-testid] for element selection
  3. Add test data to fixtures/test-data.ts
  4. Document new test scenarios in this README
  5. Keep tests modular and independent

References

Last Updated: 2026-04-19 Playwright Version: ^1.40.0 Maintainer: aInventory Development Team

Reference in New Issue View Git Blame Copy Permalink