tfm_ainventory/frontend/e2e/README.md

# 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