From 5618e9d9f8728d538aeb772c2a8b404230da7cd6 Mon Sep 17 00:00:00 2001 From: Daniel Bedeleanu Date: Sun, 19 Apr 2026 07:58:25 +0300 Subject: [PATCH] docs: create e2e test suite README with setup and execution guide --- frontend/e2e/README.md | 285 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 285 insertions(+) create mode 100644 frontend/e2e/README.md diff --git a/frontend/e2e/README.md b/frontend/e2e/README.md new file mode 100644 index 00000000..00cd7098 --- /dev/null +++ b/frontend/e2e/README.md @@ -0,0 +1,285 @@ +# 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 + +```bash +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: +```bash +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 +```bash +npx playwright test +``` + +### Specific Workflow +```bash +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 +```bash +npx playwright test --ui +``` + +### Debug Mode +```bash +npx playwright test --debug +``` + +### Generate Report +```bash +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: + +```bash +# 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: + +```bash +# 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 +```typescript +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 +```typescript +import * as auth from '../fixtures/auth'; +import * as db from '../fixtures/db'; +import { TEST_ITEMS } from '../fixtures/test-data'; +``` + +### Custom Assertions +```typescript +import * as assertions from '../utils/assertions'; + +await assertions.assertUserAuthenticated(page); +await assertions.assertStockAdjustmentVisible(page, itemName); +``` + +### Helpers +```typescript +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 + +- [Playwright Documentation](https://playwright.dev) +- [Test Assertions](./utils/assertions.ts) +- [Test Fixtures](./fixtures/) +- [Playwright Config](./playwright.config.ts) + +--- + +**Last Updated:** 2026-04-19 +**Playwright Version:** ^1.40.0 +**Maintainer:** aInventory Development Team