Device Testing

This document describes how podkit verifies iPod device compatibility through automated testing and real hardware confirmation.

Overview

Device compatibility verification happens at two levels:

Automated E2E Tests: Verify operations work using dummy iPod databases
Real Hardware Confirmation: Verify a real iPod works end-to-end

Both levels are tracked in Supported Devices.

Testing Levels

Level 1: Dummy iPod Tests (E2E)

Dummy iPod tests use @podkit/gpod-testing to create temporary iPod database structures without real hardware. These tests verify:

Database creation and initialization
Track adding, updating, and removal
Playlist management
Artwork handling
Database integrity after operations

What dummy tests prove: The code correctly handles the iTunesDB format for a given model.

What dummy tests don’t prove: The actual hardware accepts and plays the content.

Level 2: Real Hardware Tests

Real hardware tests require a physical iPod connected to the test machine. These verify:

Device detection and mounting
Actual file transfer to device
Database written correctly for device firmware
Content actually playable on device

How to run:

export IPOD_MOUNT=/Volumes/iPod
bun run test:e2e:real

Level 3: User Confirmation

Nothing beats a user report confirming “I synced my music library and it plays fine.”

Writing Tests for a Model

Model-specific tests use @podkit/gpod-testing to create temporary iPod databases. Place these alongside other integration tests in the relevant package (typically packages/libgpod-node or packages/podkit-core).

import { describe, it, expect } from 'bun:test';
import { withTestIpod } from '@podkit/gpod-testing';

describe('iPod Video 60GB (MA147)', () => {
  it('initializes with correct model', async () => {
    await withTestIpod(async (ipod) => {
      const info = await ipod.info();
      expect(info.trackCount).toBe(0);
    }, { model: 'MA147' });
  });

  it('syncs music tracks', async () => {
    await withTestIpod(async (ipod) => {
      await ipod.addTrack({
        title: 'Test Song',
        artist: 'Test Artist',
        album: 'Test Album',
      });

      const info = await ipod.info();
      expect(info.trackCount).toBe(1);
    }, { model: 'MA147' });
  });
});

Note: iPod Classic 6th gen+ models (MB565, MC297) require a FirewireID that libgpod does not auto-generate, so they cannot be used with createTestIpod(). Use iPod Video models (MA147, MA002) for test environments instead. See packages/gpod-testing/README.md for supported models.

Update Supported Devices

After adding tests, update the documentation table:

| iPod Classic 160GB | 7th | Full | :test_tube: | :grey_question: | Model: MC293 |

Real Hardware Testing

Prerequisites

Physical iPod device
iPod mounted and accessible
E2E test suite installed

Running Tests

From the repository root:

export IPOD_MOUNT=/Volumes/IPOD
bun run test:e2e:real

Or from the e2e-tests package directly:

cd packages/e2e-tests
IPOD_TARGET=real IPOD_MOUNT=/Volumes/IPOD bun test

What to Verify

Registration: podkit device add myipod /Volumes/IPOD registers the device
Info: podkit device info shows correct model/generation
Sync: podkit sync transfers files successfully
Playback: Manual verification that content plays
Artwork: Album art displays correctly
Playlists: Created playlists appear on device

Documenting Results

After successful testing, update Supported Devices:

| iPod Video 60GB | 5th | Full | :test_tube: | :white_check_mark: | MA003, MA147 |

Contributing Device Confirmations

If you have an iPod and want to help verify support:

Run the tests: bun run test:e2e with your device
Test manually: Sync some music, verify playback
Report results: Open a PR updating supported devices with:
- Model number
- Firmware version (if known)
- What worked/didn’t work
- Any quirks observed

Example PR Description

## Device Confirmation: iPod Nano 4th Gen (MB598)

### Hardware
- Model: MB598 (8GB, blue)
- Firmware: 1.0.4

### Test Results
- [x] Music sync
- [x] Artwork display
- [x] Video playback
- [x] Playlist creation
- [x] Smart playlists

### Observations
- First sync after reset took ~30s for 100 tracks
- Artwork displays correctly at all sizes