# E2E Test Suite

Comprehensive End-to-End test suite for the MetaDrivenPlatform4AI (NexusCRM) platform.

## Quick Links

- [Environment Setup](./ENV_SETUP.md)
- [Infrastructure Guide](./INFRASTRUCTURE.md)
- [Troubleshooting](./docs/TROUBLESHOOTING.md)
- [Missing Test IDs](./docs/MISSING_TEST_IDS.md)

## Overview

This E2E test suite contains **380+ tests** across **17 spec files** covering:

| Category | Test Count | Description |
|----------|------------|-------------|
| Authentication | 24 | Login, logout, session management |
| Navigation | 18 | Menu, breadcrumbs, routing |
| Accounts CRUD | 28 | Create, read, update, delete accounts |
| Contacts CRUD | 24 | Contact management |
| Opportunities CRUD | 26 | Deal/pipeline management |
| Search | 16 | Global and advanced search |
| Setup/Landing | 14 | First-time setup, onboarding |
| Object Manager | 20 | Custom object administration |
| Object Creation | 16 | Custom object records |
| Object Fields | 18 | Field management |
| Dashboards (List) | 14 | Dashboard listing |
| Dashboards (View) | 16 | Dashboard viewing |
| Dashboards (Create) | 18 | Dashboard creation/editing |
| Reports | 22 | Report management |
| Flows | 20 | Automation workflows |
| Approvals | 18 | Approval processes |
| Approval Queue | 16 | Pending approval management |

## Prerequisites

- **Node.js** v20.x or later
- **npm** v10.x or later
- **Go** 1.22.x or later
- **Docker** (for local TiDB)
- **MySQL Client** (optional, for database operations)

## Installation

```bash
# Navigate to project root
cd MetaDrivenPlatform4AI

# Install dependencies
npm install

# Install Playwright browsers
npx playwright install --with-deps chromium

# Copy environment template
cp tests/e2e/.env.test.template tests/e2e/.env.test
```

## Running Tests

### Basic Commands

```bash
# Run all tests
npm run e2e

# Run tests with UI visible
npm run e2e:headed

# Run tests in debug mode
npm run e2e:debug

# Run tests in UI mode (interactive)
npm run e2e:ui

# View test report
npm run e2e:report

# Generate selectors using codegen
npm run e2e:codegen
```

### Tag-Based Execution

```bash
# Run smoke tests (critical path)
npm run e2e:smoke

# Run critical tests
npm run e2e:critical

# Run account-related tests
npm run e2e:accounts

# Run dashboard tests
npm run e2e:dashboards

# Run authentication tests
npm run e2e:auth

# Run approval tests
npm run e2e:approvals

# Run tests by tag
npx playwright test --grep @smoke
npx playwright test --grep "@accounts|@contacts"
```

### Project-Specific Execution

```bash
# Run on Chromium only
npx playwright test --project=chromium

# Run on Firefox only
npx playwright test --project=firefox

# Run unauthenticated tests
npx playwright test --project=chromium-unauth
```

### File-Specific Execution

```bash
# Run specific test file
npx playwright test tests/e2e/specs/auth.spec.ts

# Run tests matching pattern
npx playwright test auth
npx playwright test accounts-crud
```

### CI Report Publishing

The GitHub Actions workflow in [`.github/workflows/e2e-tests.yml`](../../.github/workflows/e2e-tests.yml) can publish the generated Playwright HTML report to a dedicated Vercel project after every run.

Add these GitHub repository secrets before enabling it:

- `VERCEL_TOKEN`
- `VERCEL_ORG_ID`
- `VERCEL_PROJECT_ID`

The workflow behavior is:

- It writes the Playwright HTML report to `tests/e2e/playwright-report/` and uploads it as the `playwright-results` artifact when `index.html` is generated.
- If the three Vercel secrets are present, it also deploys the same report as a Vercel preview deployment.
- The deployment URL is written into the GitHub Actions job summary.
- It updates a single bot comment on the related PR; if no PR is associated with the commit, it falls back to a commit comment.
- The comment includes the E2E status, test counts, artifact counts, workflow run link, and the Vercel report link when available.

Recommended setup:

1. Create a separate Vercel project just for E2E reports.
2. Link that project locally with `vercel link` in a temporary folder.
3. Copy the generated `orgId` and `projectId` from `.vercel/project.json` into the GitHub secrets above.

## Test Structure

```
tests/e2e/
├── specs/                      # Test specifications
│   ├── auth.spec.ts           # Authentication tests
│   ├── navigation.spec.ts     # Navigation tests
│   ├── accounts-crud.spec.ts  # Account CRUD tests
│   ├── contacts-crud.spec.ts  # Contact CRUD tests
│   ├── opportunities-crud.ts  # Opportunity tests
│   ├── search.spec.ts         # Search tests
│   ├── setup-landing.spec.ts  # Setup/onboarding
│   ├── object-manager.spec.ts # Custom objects
│   ├── object-creation.spec.ts# Object records
│   ├── object-fields.spec.ts  # Field management
│   ├── dashboard-list.spec.ts # Dashboard listing
│   ├── dashboard-view.spec.ts # Dashboard viewing
│   ├── dashboard-creation.ts  # Dashboard creation
│   ├── reports.spec.ts        # Report tests
│   ├── flows.spec.ts          # Automation flows
│   ├── approvals.spec.ts      # Approval processes
│   └── approval-queue.spec.ts # Approval queue
├── fixtures/                   # Test fixtures
│   ├── index.ts               # Fixture exports
│   ├── auth.fixture.ts        # Auth fixtures
│   └── data.fixture.ts        # Data fixtures
├── utils/                      # Utilities
│   ├── app-helpers.ts         # App-level helpers
│   └── wait-helpers.ts        # Wait utilities
├── seed/                       # Seed data
│   ├── accounts.seed.ts       # Account data
│   ├── contacts.seed.ts       # Contact data
│   ├── opportunities.seed.ts  # Opportunity data
│   └── index.ts               # Seed exports
├── scripts/                    # Setup scripts
│   ├── reset-db.sh            # DB reset script
│   ├── seed-test-data.go      # Data seeding
│   └── validate-env.sh        # Environment check
├── docs/                       # Documentation
│   ├── MISSING_TEST_IDS.md    # Test ID audit
│   └── TROUBLESHOOTING.md     # Troubleshooting guide
├── playwright.config.ts        # Configuration
├── global-setup.ts             # Global setup
└── ENV_SETUP.md                # Setup guide
```

## Writing Tests

### Basic Test Structure

```typescript
import { test, expect } from '../fixtures';
import { waitForLoad } from '../utils/wait-helpers';

test.describe('Feature Name @tag1 @tag2', () => {
  test.beforeEach(async ({ authenticatedPage }) => {
    await authenticatedPage.goto('/feature');
    await waitForLoad(authenticatedPage);
  });

  test('should do something @smoke', async ({ authenticatedPage }) => {
    // Test logic here
    await expect(authenticatedPage.getByTestId('element')).toBeVisible();
  });
});
```

### Using Fixtures

```typescript
import { test, expect } from '../fixtures';

test('example', async ({
  authenticatedPage,  // Logged in as admin
  testUserPage,       // Logged in as test user
  readonlyPage,       // Logged in as read-only
  guestPage,          // Not logged in
  testData,           // Seed data access
  dbCleanup,          // Auto-cleanup
  apiRequest          // API helper
}) => {
  // Your test here
});
```

### Selector Priority

Always use selectors in this order of preference:

1. **data-testid** (Most stable)
   ```typescript
   await page.getByTestId('submit-button').click();
   ```

2. **ARIA roles + accessible names**
   ```typescript
   await page.getByRole('button', { name: 'Submit' }).click();
   ```

3. **Text content**
   ```typescript
   await page.getByText('Welcome').isVisible();
   ```

4. **CSS selectors** (Last resort)
   ```typescript
   await page.locator('.btn-primary').click();
   ```

### Wait Helpers

```typescript
import { waitForLoad } from '../utils/wait-helpers';

// Wait for page load
await waitForLoad(page);
```

## Test Tags

| Tag | Description | Usage |
|-----|-------------|-------|
| `@smoke` | Critical path tests | Quick validation |
| `@critical` | Business-critical tests | Must pass |
| `@accounts` | Account-related tests | Module filtering |
| `@contacts` | Contact-related tests | Module filtering |
| `@opportunities` | Opportunity tests | Module filtering |
| `@dashboards` | Dashboard tests | Module filtering |
| `@reports` | Report tests | Module filtering |
| `@flows` | Automation tests | Module filtering |
| `@approvals` | Approval tests | Module filtering |
| `@admin` | Admin-only tests | Permission filtering |
| `@create` | Creation tests | Action filtering |
| `@edit` | Edit tests | Action filtering |
| `@delete` | Delete tests | Action filtering |
| `@validation` | Validation tests | Type filtering |
| `@ux` | UX-related tests | Type filtering |

## Configuration

### Environment Variables

Create `tests/e2e/.env.test`:

```bash
# Frontend
PLAYWRIGHT_BASE_URL=http://localhost:5173

# Backend API
PLAYWRIGHT_API_URL=http://localhost:3001

# Database
TIDB_HOST=localhost
TIDB_PORT=4000
TIDB_USER=root
TIDB_PASSWORD=
TIDB_DATABASE=nexuscrm_test

# Test users
TEST_ADMIN_EMAIL=admin@nexuscrm.test
# Required — set to your environment's admin password
TEST_ADMIN_PASSWORD=
TEST_USER_EMAIL=testuser@nexuscrm.test
TEST_USER_PASSWORD=User123!
```

### Playwright Configuration

Key settings in `playwright.config.ts`:

| Setting | Value | Description |
|---------|-------|-------------|
| `timeout` | 30000ms | Max test duration |
| `actionTimeout` | 15000ms | Max action duration |
| `retries` | 2 (CI) / 0 (local) | Retry on failure |
| `workers` | 2 (CI) / 4 (local) | Parallel execution |
| `trace` | retain-on-failure | Debug artifacts |

## CI/CD Integration

### GitHub Actions

Tests run automatically on:
- Pull requests to `main`, `develop`
- Pushes to `main`, `develop`

Tests are:
- **Sharded** across 4 parallel workers
- **Retried** 2 times on failure
- **Reported** via JUnit XML and HTML

### Artifacts

After CI runs, available artifacts:
- `playwright-results-*` - Test results
- `screenshots-*` - Failure screenshots
- `playwright-merged-results` - Combined results

## Performance

### Performance Thresholds

| Metric | Warning | Critical |
|--------|---------|----------|
| Test Duration | >30s | >60s |
| Page Load | >5s | >10s |
| API Response | >2s | >5s |

## Debugging

### Debug Mode

```bash
# Run in debug mode
npx playwright test --debug

# Debug specific test
npx playwright test auth.spec.ts --debug
```

### Trace Viewer

```bash
# Open trace viewer
npx playwright show-trace test-results/trace.zip
```

### Video Recording

Videos are recorded on failure and saved to `test-results/`.

## Troubleshooting

See [TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) for common issues and solutions.

### Quick Fixes

```bash
# Reset database
./tests/e2e/scripts/reset-db.sh

# Regenerate auth state
rm -rf tests/e2e/.auth/*.json
npm run e2e

# Clear Playwright cache
rm -rf .cache/
rm -rf node_modules/.cache/

# Reinstall browsers
npx playwright install --with-deps
```

## Support

For questions or issues:
1. Check [TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md)
2. Review existing test examples in `specs/`
3. Consult [Playwright Documentation](https://playwright.dev)

## Contributing

### Adding New Tests

1. Create test file in `specs/` with appropriate name
2. Add test tags in describe block
3. Use fixtures for setup
4. Use `data-testid` selectors
5. Use wait helpers instead of hardcoded timeouts
6. Register created data for cleanup

### Code Review Checklist

- [ ] Tests are tagged appropriately
- [ ] Uses `data-testid` selectors
- [ ] Uses wait helpers
- [ ] Cleans up test data
- [ ] Has descriptive test names
- [ ] Follows existing patterns

## License

Internal use only - MetaDrivenPlatform4AI