crowd-funder-for-time-pwa/test-playwright/README.md

# Playwright Test Suite

This directory contains the automated end-to-end test suite for Time Safari using Playwright. The tests verify critical functionality across web and mobile platforms.

## Test Structure

Tests are organized by feature area and numbered for execution order.

## Key Files

- `testUtils.ts` - Shared test utilities and helper functions
- `TESTING.md` - Detailed testing guide and manual test procedures
- `playwright.config-local.ts` - Playwright configuration for local testing
- `exported-data.json` - Test data for import/export testing

## Prerequisites

1. Endorser server running locally (see TESTING.md for setup)

   ```bash
   git clone https://github.com/time-endorser/endorser-ch.git
   cd endorser-ch
   npm install
   test/test.sh
   cp .env.local .env
   NODE_ENV=test-local npm run dev
   ```

2. Playwright browsers installed:

   ```bash
   npx playwright install
   ```

3. For mobile testing:
   - XCode (for iOS)
   - Android Studio or connected Android device

## Running Tests

### Full Test Suite

```bash
# Run all tests (web + mobile)
npm run test:all

# Run web-only tests
npm run test:web
```

### Individual Tests

```bash
# Run a specific test with tracing
npx playwright test -c playwright.config-local.ts --trace on test-playwright/40-add-contact.spec.ts
```

### Test Environment Options

1. Local Endorser Server (default):

   ```bash
   NODE_ENV=test-local npm run dev
   ```

2. Global Test Server:

   ```bash
   VITE_DEFAULT_ENDORSER_API_SERVER=https://test-ledger.time.com npm run dev
   ```

3. Minimal Test Data:

   ```bash
   rm ../endorser-ch-test-local.sqlite3
   NODE_ENV=test-local npm run flyway migrate
   NODE_ENV=test-local npm run test test/controller0
   NODE_ENV=test-local npm run dev
   ```

## Test Data

The test suite uses predefined test users, with User #0 having registration privileges. To use it: Profile -> Advanced -> Switch Identifier -> Add Another Identity -> You Have A Seed -> Advanced -> Use mnemonic for Test User #0 -> Import

More details available in TESTING.md

## Timeout Behavior

**Important**: Playwright tests will fail if any operation exceeds its specified timeout. This is intentional behavior to catch performance issues and ensure tests don't hang indefinitely.

### Timeout Types and Defaults

1. **Test Timeout**: 45 seconds (configured in `playwright.config-local.ts`)
   - Maximum time for entire test to complete
   - Test fails if exceeded

2. **Expect Timeout**: 5 seconds (Playwright default)
   - Maximum time for assertions (`expect()`) to pass
   - Test fails if assertion doesn't pass within timeout

3. **Action Timeout**: No default limit
   - Maximum time for actions (`click()`, `fill()`, etc.)
   - Can be set per action if needed

4. **Function Timeout**: Specified per `waitForFunction()` call
   - Example: `{ timeout: 5000 }` = 5 seconds
   - **Test will fail if function doesn't return true within timeout**

### Common Timeout Patterns in Tests

```typescript
// Wait for UI element to appear (5 second timeout)
await page.waitForFunction(() => {
  const buttons = document.querySelectorAll('div[role="alert"] button');
  return Array.from(buttons).some(button => button.textContent?.includes('No'));
}, { timeout: 5000 });

// If this times out, the test FAILS immediately
```

### Why Tests Fail on Timeout

- **Performance Issues**: Slow UI rendering or network requests
- **Application Bugs**: Missing elements or broken functionality  
- **Test Environment Issues**: Server not responding or browser problems
- **Race Conditions**: Elements not ready when expected

### Timeout Configuration

To adjust timeouts for specific tests:

```typescript
test('slow test', async ({ page }) => {
  test.setTimeout(120000); // 2 minutes for entire test
  
  await expect(page.locator('button')).toBeVisible({ timeout: 15000 }); // 15 seconds for assertion
  
  await page.click('button', { timeout: 10000 }); // 10 seconds for action
});
```

### Debugging Timeout Failures

1. **Check Test Logs**: Look for timeout error messages
2. **Run with Tracing**: `--trace on` to see detailed execution
3. **Run Headed**: `--headed` to watch test execution visually
4. **Check Server Logs**: Verify backend is responding
5. **Increase Timeout**: Temporarily increase timeout to see if it's a performance issue

## Troubleshooting

Common issues and solutions:

1. **Test Failures**
   - Some tests may fail intermittently - try rerunning
   - Check Endorser server logs for backend issues
   - Verify test environment setup
   - **Timeout failures indicate real performance or functionality issues**

2. **Mobile Testing**
   - Ensure XCode/Android Studio is running
   - Check device connectivity
   - Verify browser installation

3. **Data Issues**
   - Clear browser data if tests fail due to stale state
   - Reset IndexedDB if needed
   - Check service worker status

4. **Timeout Issues**
   - Check if UI elements are loading slowly
   - Verify server response times
   - Consider if timeout values are appropriate for the operation
   - Use `--headed` mode to visually debug timeout scenarios

For more detailed troubleshooting, see TESTING.md.

## Contributing

When adding new tests:

1. Follow the existing naming convention
2. Use testUtils.ts for common operations
3. Add appropriate comments and documentation
4. Update this README if adding new test categories
5. Consider both web and mobile platforms

## Related Documentation

- [TESTING.md](./TESTING.md) - Detailed testing guide
- [Playwright Documentation](https://playwright.dev/docs/intro)
- Endorser server documentation for test setup