# Testing Guide

Start with [README.md](./README.md). This file has more details.

## Test User Setup

### Register New User on Test Server

On the test server, User #0 has rights to register others. Import User #0 with this seed phrase:

```bash
rigid shrug mobile smart veteran half all pond toilet brave review universe ship congress found yard skate elite apology jar uniform subway slender luggage
```

This corresponds to: `did:ethr:0x0000694B58C2cC69658993A90D3840C560f2F51F`

(Other test users can be found [here](https://github.com/trentlarson/endorser-ch/blob/master/test/util.js).)

## Manual Testing Steps

### Identity Management

1. Create multiple identifiers:
   - Go to "Your Identity" screen
   - Click "Advanced"
   - Click "Switch Identity / No Identity"
   - Click "Add Another Identity..."

2. Create keys with alternate tools:
   - See [openssl_signing_console.rst](openssl_signing_console.rst) for JWT creation with local keypairs

### Manual Walk-through Test Checklist

1. Initial Setup
   - Backup seed & data
   - Get CSV dump from Endorser Mobile
   - Check DB migration compatibility
   - Verify version update

2. Environment Setup
   - Clear browser data
   - Add identity
   - Import Time Safari contacts and CSV contacts
   - Verify test API usage

3. Fresh Install Testing
   - Clear browser data
   - Check account page before home page
   - Verify ID generation
   - Test feed without names
   - Verify contact URL copying
   - Check messaging on all pages
   - Verify project discovery
   - Test contact addition without ID

4. Feature Testing
   - Test identifier switching
   - Check registration limits
   - Verify gift recording
   - Test offer & delivery
   - Check contact registration
   - Test notifications
   - Verify export/import
   - Test location features
   - Check third-user connections
   - Test mobile image sharing

## Data Reset Instructions

### Chromium

```bash
 rm -rf profiles/dev2 && \ 
 mkdir -p profiles/dev2 && \
 chromium --user-data-dir=profiles/dev2 --start-maximized --auto-open-devtools-for-tabs http://localhost:8080
```

### Firefox

Here is the equivalent command for **Firefox** using a custom profile and opening a local page:

```bash
rm -rf profiles/dev2 && \
mkdir -p profiles/dev2 && \
firefox --no-remote --profile $(realpath profiles/dev2) --devtools --new-window http://localhost:8080
```

## Timeout Behavior

**Critical Understanding**: Playwright tests will **fail immediately** if any timeout is exceeded. This is intentional behavior to catch performance issues and ensure tests don't hang indefinitely.

### Key Timeout Facts

- **Test Timeout**: 45 seconds (entire test must complete)
- **Expect Timeout**: 5 seconds (assertions must pass)  
- **Function Timeout**: As specified (e.g., `{ timeout: 5000 }` = 5 seconds)
- **Action Timeout**: No default limit (can be set per action)

### What Happens on Timeout

```typescript
// This will FAIL the test if buttons don't appear within 5 seconds
await page.waitForFunction(() => {
  const buttons = document.querySelectorAll('div[role="alert"] button');
  return Array.from(buttons).some(button => button.textContent?.includes('No'));
}, { timeout: 5000 });
```

**If timeout exceeded**: Test fails immediately with `TimeoutError` - no recovery, no continuation.

### Debugging Timeout Failures

1. **Visual Debugging**: Run with `--headed` to watch test execution
2. **Tracing**: Use `--trace on` for detailed execution logs
3. **Server Check**: Verify Endorser server is responding quickly
4. **Performance**: Check if UI elements are loading slowly
5. **Timeout Adjustment**: Temporarily increase timeout to isolate performance vs functionality issues

### Common Timeout Scenarios

- **UI Elements Not Appearing**: Check if alerts/dialogs are rendering correctly
- **Network Delays**: Verify server response times
- **Race Conditions**: Elements not ready when expected
- **Browser Issues**: Slow rendering or JavaScript execution

## Troubleshooting

1. Identity Errors:
   - "No keys for ID" errors may occur when current account was erased
   - Account switching can cause issues with erased accounts

2. **Timeout Failures**:
   - **These are NOT flaky tests** - they indicate real performance or functionality issues
   - Check server logs for slow responses
   - Verify UI elements are rendering correctly
   - Use `--headed` mode to visually debug the issue

3. If you find yourself wanting to see the testing process try something like this:

```
npx playwright test -c playwright.config-local.ts test-playwright/60-new-activity.spec.ts --grep "New offers for another user" --headed
```

This command allows you to:

- **Run a specific test file**: `test-playwright/60-new-activity.spec.ts`
- **Filter to a specific test**: `--grep "New offers for another user"` runs only tests with that name
- **See the browser**: `--headed` opens the browser window so you can watch the test execute
- **Use local config**: `-c playwright.config-local.ts` uses the local configuration file

This is useful when you want to observe the testing process visually rather than running tests in headless mode. It's particularly helpful for debugging test failures or understanding how the application behaves during automated testing.