# Metronome Test Suite

This directory contains Playwright tests for the metronome functionality in jam-ui.

## Test Coverage

### metronome-controls.spec.ts

Tests the metronome feature including:

1. **Opening Metronome** (`should open metronome controls`)
   - Opens metronome via Open menu → Metronome
   - Verifies metronome track appears in session
   - Checks for metronome heading and close button

2. **Adjusting BPM in Popup** (`should allow adjusting BPM with slider in popup`)
   - Tests BPM slider in popup control window
   - Currently skipped due to WindowPortal complexity
   - Requires popup window handling with context.waitForEvent('page')

3. **Closing Metronome** (`should close metronome from main window`)
   - Clicks close button on metronome track
   - Verifies metronome track is removed
   - Ensures user stays in session

4. **Metronome Display** (`should display metronome track with VU meter and gain controls`)
   - Verifies metronome icon displays
   - Checks for VU meter component
   - Validates session track structure

5. **Popup Controls** (`should adjust metronome settings in popup window`)
   - Comprehensive test for all metronome settings
   - Currently skipped - manual testing recommended
   - Would test: BPM, sound, meter, cricket toggle, apply button

## Running Tests

### Prerequisites

1. Start the jam-ui development server:
   ```bash
   cd jam-ui
   npm start
   ```

2. Ensure the Rails backend is running:
   ```bash
   cd web
   bundle exec rails s
   ```

### Run All Metronome Tests

```bash
cd jam-ui
npx playwright test test/metronome --config=playwright.chrome.config.ts
```

### Run Individual Test

```bash
npx playwright test test/metronome/metronome-controls.spec.ts --config=playwright.chrome.config.ts
```

### Run in UI Mode (Interactive)

```bash
npx playwright test test/metronome --ui
```

### Run in Headed Mode (Watch Browser)

```bash
npx playwright test test/metronome --headed
```

## Test Helpers

### openMetronome(page)

Helper function to open metronome in a session:

```typescript
async function openMetronome(page: Page) {
  await page.locator('button:has-text("Open")').click();
  await page.waitForSelector('.dropdown-menu.show');
  await page.locator('button.dropdown-item:has-text("Metronome")').click();
  await page.waitForTimeout(1000);
}
```

## Known Limitations

1. **WindowPortal Popup Testing**: The metronome controls open in a separate popup window (WindowPortal), which requires special handling in Playwright. Some tests are skipped due to this complexity.

2. **VU Meter Validation**: VU meters require actual audio data from the native client. Tests verify the VU component is present but don't test actual meter movement.

3. **Native Client Calls**: Tests cannot directly verify `jamClient.SessionSetMetronome()` calls. Backend verification would require additional instrumentation.

## Test Data Flow

```
User Action → UI Component → jamClient → Native Audio Engine
                                              ↓
                                         Backend API
                                              ↓
                                         Session State
```

Tests primarily verify UI behavior and component rendering. Backend and audio engine behavior should be tested separately.

## Future Improvements

- [ ] Add tests for metronome settings persistence
- [ ] Test metronome behavior during recording (should be blocked)
- [ ] Test metronome with unstable clocks warning
- [ ] Add visual regression tests for metronome UI
- [ ] Test metronome audio output (if feasible)
- [ ] Add unit tests for JKSessionMetronomePlayer component
- [ ] Test metronome state synchronization across popup and main window

## Related Components

- `src/components/client/JKSessionMetronome.js` - Metronome track display
- `src/components/client/JKSessionMetronomePlayer.js` - Metronome controls popup
- `src/components/client/JKSessionOpenMenu.js` - Open menu with metronome option
- `src/components/client/JKSessionScreen.js` - Session screen integration
