docs: create e2e test suite README with setup and execution guide
This commit is contained in:
285
frontend/e2e/README.md
Normal file
285
frontend/e2e/README.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user