@qawolf/run-globals-ios

iOS testing utilities for QA Wolf - audio recording and photos management.

This package provides standalone functions for interacting with iOS devices through WebDriverIO, following the same flat API pattern as run-globals-android.

Installation

npm install @qawolf/run-globals-ios

Peer Dependencies

This package requires WebDriverIO as a peer dependency:

npm install webdriverio webdriver

Usage

import * as ios from '@qawolf/run-globals-ios';

// Speaker audio recording (captures device audio output)
const session = await ios.startSpeakerRecording(driver);
console.log(`Recording started with session ID: ${session.id}`);

// Wait for some audio to be recorded
await new Promise(resolve => setTimeout(resolve, 5000));

// Stop recording - this also calculates the fingerprint automatically
const file = await ios.stopSpeakerRecording(driver, session.id);
console.log(`Recording saved to: ${file.filename}`);
if (file.fingerprint) {
  console.log(`Fingerprint has ${file.fingerprint.length} values`);
}

// Download the audio file
const audioBuffer = await ios.downloadSpeakerRecording(driver, file.filename);
fs.writeFileSync('/tmp/recording.wav', audioBuffer);

// Calculate fingerprint for a reference audio file
const referenceAudio = fs.readFileSync('/tmp/reference.wav');
const fingerprint = await ios.calculateAudioFingerprint(driver, referenceAudio);
console.log(`Reference duration: ${fingerprint.duration}s`);

// Save a photo from local filesystem to device Photos library
const result = await ios.savePhoto(driver, '/Users/me/test-photo.jpg');
if (result.success) {
  console.log('Photo saved to library');
}

// List all photos in the library
const photoList = await ios.listPhotos(driver);
console.log(`Found ${photoList.totalCount} photos`);

// Clean up - delete all photos (useful for test cleanup)
await ios.deleteAllPhotos(driver);
console.log('All photos deleted');

API Reference

Speaker Audio Recording Functions

startSpeakerRecording(driver)

Start recording speaker/system audio output on the iOS device.

• Parameters:
  • driver: Browser - WebDriverIO browser instance
• Returns: Promise<SpeakerRecordingSession> - Session information with ID
• Throws: Error if recording fails to start

stopSpeakerRecording(driver, sessionId)

Stop speaker audio recording and finalize the file. Automatically calculates audio fingerprint.

• Parameters:
  • driver: Browser - WebDriverIO browser instance
  • sessionId: string - Session ID from startSpeakerRecording()
• Returns: Promise<SpeakerRecordingFile> - File information including optional fingerprint
• Throws: Error if session ID is invalid or stop fails

downloadSpeakerRecording(driver, filename)

Download a recorded speaker audio file as a Buffer (WAV format).

• Parameters:
  • driver: Browser - WebDriverIO browser instance
  • filename: string - Filename from stopSpeakerRecording()
• Returns: Promise<Buffer> - Audio file contents
• Throws: Error if file doesn't exist

calculateAudioFingerprint(driver, audioData)

Calculate audio fingerprint from audio data.

• Parameters:
  • driver: Browser - WebDriverIO browser instance
  • audioData: Buffer | string - WAV audio data as Buffer or base64 string
• Returns: Promise<AudioFingerprint> - Fingerprint and duration
• Throws: Error if audio data is invalid

Photo Functions

savePhoto(driver, filePath)

Save a file from the filesystem to the device Photos library. Handles the complete workflow including file transfer and cleanup.

• Parameters:
  • driver: Browser - WebDriverIO browser instance
  • filePath: string - Absolute path to file on the filesystem
• Returns: Promise<SavePhotoResult> - Success status and optional message
• Throws: Error if file doesn't exist or save fails

listPhotos(driver)

List all photos and videos from the Photos library.

• Parameters:
  • driver: Browser - WebDriverIO browser instance
• Returns: Promise<ListPhotosResult> - Result with assets array and count
• Throws: Error if listing fails

deleteAllPhotos(driver)

Delete all photos and videos from the Photos library. Useful for test cleanup.

• Parameters:
  • driver: Browser - WebDriverIO browser instance
• Returns: Promise<DeletePhotosResult> - Result with deleted count
• Throws: Error if deletion fails

Types

SpeakerRecordingSession

interface SpeakerRecordingSession {
  id: string;        // Unique session identifier
  status: string;    // Recording status
}

SpeakerRecordingFile

interface SpeakerRecordingFile {
  filename: string;        // Name of the audio file
  fingerprint?: number[];  // Optional audio fingerprint (array of integers)
  duration?: number;       // Optional duration in seconds
}

AudioFingerprint

interface AudioFingerprint {
  fingerprint: number[];  // Audio fingerprint (array of integers)
  duration: number;       // Duration in seconds
}

PhotoAsset

interface PhotoAsset {
  localIdentifier: string;
  mediaType: string;
  mediaSubtype: string;
  creationDate: string;
  modificationDate: string;
  pixelWidth: number;
  pixelHeight: number;
  duration: number;
  isFavorite: boolean;
  isHidden: boolean;
}

SavePhotoResult

interface SavePhotoResult {
  success: boolean;   // Whether save was successful
  message?: string;   // Optional additional information
}

ListPhotosResult

interface ListPhotosResult {
  success: boolean;
  assets: PhotoAsset[];
  totalCount: number;
}

DeletePhotosResult

interface DeletePhotosResult {
  success: boolean;
  deletedCount: number;
  message?: string;
}

Architecture

This package provides a clean, fetch-based HTTP API for iOS testing:

• Flat API: All functions are exported directly for easy autocomplete
• Direct HTTP communication: Uses native fetch API to communicate with Appium/WebDriver server
• No driver mutation: Functions make direct HTTP calls without registering custom commands
• Full TypeScript support: Complete type definitions with comprehensive JSDoc documentation
• Explicit dependencies: Driver is passed explicitly to extract connection information

Requirements

• Node.js ^20
• WebDriverIO ^8.0.0 or ^9.0.0
• iOS device or simulator with QA Wolf iOS Agent installed
• Appium server with ios-agent running

License

MIT