Version: 1.0.0 Last Updated: 2026-02-09 Status: Production Ready

• Overview
• Platform Coverage Matrix
• Deterministic Testing Principles
• Platform-Specific Tests
• Test Execution Guide
• CI/CD Integration
• Troubleshooting

This document defines the complete E2E test matrix for nself-chat across all supported platforms. Tests are designed to be deterministic, reproducible, and non-flaky across different environments.

1. No wall-clock dependencies: Use deterministic timestamps and counters
2. Proper wait conditions: Wait for specific elements/states, not arbitrary timeouts
3. Isolated test data: Each test uses unique, generated test data
4. Deterministic seeds: Reproducible random values when needed
5. Platform parity: Same tests run across all platforms where applicable

Total Web Test Suites: 24 files, 300+ tests

Web-Specific Features:

• Visual regression testing
• Accessibility (WCAG 2.1 AA)
• Browser API compatibility
• Web Workers
• Service Workers (PWA)
• IndexedDB storage

Desktop-Specific Features:

• Native window management
• System tray integration
• Auto-updates
• Native notifications
• File system access
• Deep linking (protocol handlers)
• Keyboard shortcuts (global)
• Multi-window support

Test Configuration: See platforms/electron/e2e.config.js

Tauri-Specific Features:

• Rust IPC bridge
• System APIs
• Secure storage
• Native menus
• File dialogs

Test Configuration: See platforms/tauri/e2e.config.js

iOS-Specific Features:

• Face ID / Touch ID
• Haptic feedback
• 3D Touch
• Background refresh
• App clips
• Siri shortcuts
• HealthKit integration (future)
• CallKit integration

Test Configuration: See .detoxrc.js (iOS)

Android-Specific Features:

• Biometric authentication
• Share sheet
• Background services
• Notification channels
• Picture-in-Picture
• Split screen
• Adaptive icons
• Direct share

Test Configuration: See .detoxrc.js (Android)

Configuration: See appium.config.js (BrowserStack section)

Configuration: See appium.config.js (AWS Device Farm section)

Problem: Using Date.now() makes tests non-reproducible.

❌ Bad Pattern:

const testMessage = `Test message ${Date.now()}`

✅ Good Pattern:

import { generateTestId } from './fixtures/test-helpers'

const testMessage = `Test message ${generateTestId()}`
// Uses deterministic counter: test-1, test-2, test-3...

Problem: Arbitrary timeouts cause flakiness.

❌ Bad Pattern:

await page.waitForTimeout(1000) // Might be too short or too long

✅ Good Pattern:

await page.waitForSelector('[data-testid="message-sent"]', {
  state: 'visible',
  timeout: 10000
})

Problem: Tests interfere with each other.

❌ Bad Pattern:

test('create channel', async () => {
  await createChannel('general') // Name conflict!
})

✅ Good Pattern:

test('create channel', async ({ testContext }) => {
  const channelName = testContext.uniqueId('channel')
  await createChannel(channelName)
})

Problem: Math.random() makes debugging impossible.

❌ Bad Pattern:

const randomValue = Math.random()

✅ Good Pattern:

import { SeededRandom } from './fixtures/test-helpers'

const rng = new SeededRandom('test-seed-123')
const randomValue = rng.next()
// Always produces same sequence

Problem: Tests depend on external services.

✅ Solution: Mock all external APIs

await page.route('**/api/external/**', route => {
  route.fulfill({
    status: 200,
    body: JSON.stringify({ data: 'mocked' })
  })
})

Location: /e2e/web-only/

1. Browser API Tests (browser-apis.spec.ts)

   • IndexedDB storage
   • Service Workers
   • Web Workers
   • LocalStorage / SessionStorage
   • Clipboard API
   • File System Access API

2. Visual Regression (visual-regression.spec.ts)

   • Pixel-perfect screenshots
   • Cross-browser rendering
   • Responsive design breakpoints

3. Accessibility (accessibility.spec.ts)

   • WCAG 2.1 AA compliance
   • Screen reader compatibility
   • Keyboard navigation
   • Focus management
   • ARIA attributes

4. PWA Features (pwa.spec.ts)

   • Install prompt
   • Offline mode (Service Worker)
   • App manifest
   • Background sync

Location: /e2e/desktop-only/

1. Window Management (window-management.spec.ts)

   • Create/close windows
   • Minimize/maximize/restore
   • Multi-window state
   • Window positioning
   • Full-screen mode

2. System Integration (system-integration.spec.ts)

   • System tray/menu bar
   • Native notifications
   • Auto-launch on startup
   • Protocol handlers (deep links)
   • File associations

3. Auto-Updates (auto-updates.spec.ts)

   • Check for updates
   • Download updates
   • Install and restart
   • Rollback on failure

4. Native Menus (native-menus.spec.ts)

   • Application menu
   • Context menus
   • Keyboard shortcuts

5. File System (file-system.spec.ts)

   • Native file picker
   • Drag-drop files
   • Save/export files
   • Directory access

Location: /e2e/mobile/

Already Implemented (11 files, 295+ tests):

1. ✅ auth.spec.ts - Mobile authentication
2. ✅ messaging.spec.ts - Touch interactions
3. ✅ channels.spec.ts - Mobile navigation
4. ✅ search.spec.ts - Mobile search UI
5. ✅ attachments.spec.ts - Camera, gallery, files
6. ✅ notifications.spec.ts - Push notifications
7. ✅ offline.spec.ts - Offline mode, sync
8. ✅ deep-linking.spec.ts - App links, universal links
9. ✅ network.spec.ts - Network conditions
10. ✅ performance.spec.ts - Mobile performance benchmarks

Additional Mobile Tests Needed:

11. Biometric Authentication (biometric-auth.spec.ts)

    • Face ID / Touch ID (iOS)
    • Fingerprint (Android)
    • Fallback to PIN/password

12. Gestures (gestures.spec.ts)

    • Swipe to delete
    • Pull to refresh
    • Pinch to zoom
    • Long press
    • Swipe navigation

13. Device Features (device-features.spec.ts)

    • Camera capture
    • Photo library
    • Share sheet
    • Contact picker
    • Location services
    • Haptic feedback

14. Background Behavior (background-behavior.spec.ts)

    • App backgrounding
    • App foregrounding
    • Background refresh
    • Memory warnings
    • State restoration

15. Orientation (orientation.spec.ts)

    • Portrait mode
    • Landscape mode
    • Orientation lock
    • Layout adaptation

Location: /e2e/ (root)

These tests run on all platforms:

1. ✅ auth.spec.ts - Authentication flows
2. ✅ chat.spec.ts - Core messaging
3. ✅ channel-management.spec.ts - Channel CRUD
4. ✅ message-sending.spec.ts - Send/edit/delete
5. ✅ settings.spec.ts - User settings
6. ✅ search.spec.ts - Search functionality
7. ✅ calls.spec.ts - Voice/video calls
8. ✅ wallet.spec.ts - Crypto wallet
9. ✅ bots.spec.ts - Bot interactions
10. ✅ admin.spec.ts - Admin dashboard
11. ✅ setup-wizard.spec.ts - First-run setup
12. ✅ i18n.spec.ts - Internationalization
13. ✅ payments.spec.ts - Payment flows
14. ✅ moderation-workflow.spec.ts - Moderation
15. ✅ ai-summarization.spec.ts - AI features

# Run all web tests
pnpm test:e2e

# Specific browser
pnpm test:e2e --project=chromium
pnpm test:e2e --project=firefox
pnpm test:e2e --project=webkit

# Mobile viewport
pnpm test:e2e --project=mobile-chrome
pnpm test:e2e --project=mobile-safari

# Debug mode (headed + inspector)
pnpm test:e2e --headed --debug

# Specific test file
pnpm test:e2e e2e/auth.spec.ts

Electron:

# Build and test
cd platforms/electron
pnpm build
pnpm test:e2e

# Platform-specific
pnpm test:e2e:mac
pnpm test:e2e:windows
pnpm test:e2e:linux

Tauri:

# Build and test
cd platforms/tauri
pnpm build
pnpm test:e2e

# Platform-specific
pnpm test:e2e:mac
pnpm test:e2e:windows
pnpm test:e2e:linux

iOS Simulator:

# Build iOS app
cd platforms/capacitor
pnpm build:ios

# Run Detox tests
pnpm detox test --configuration ios.sim.debug

# Specific device
pnpm detox test --configuration ios.14.debug
pnpm detox test --configuration ios.se.debug

Android Emulator:

# Build Android app
cd platforms/capacitor
pnpm build:android

# Run Detox tests
pnpm detox test --configuration android.emu.debug

# Tablet
pnpm detox test --configuration android.tablet.debug

Real Devices (Appium):

# Local devices
pnpm test:e2e:appium

# BrowserStack
export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_key
pnpm test:e2e:browserstack

# AWS Device Farm
export AWS_DEVICE_FARM_PROJECT_ARN=arn:aws:...
pnpm test:e2e:aws

Tests run automatically on:

• Pull Requests: Core tests (web + mobile simulators)
• Main Branch: Full test suite
• Daily Scheduled: Real device tests (BrowserStack)
• Release Tags: Complete platform matrix

GitHub Actions Workflows:

• .github/workflows/e2e-web.yml - Web tests (3 browsers)
• .github/workflows/e2e-desktop.yml - Desktop tests (3 platforms)
• .github/workflows/e2e-mobile.yml - Mobile tests (iOS + Android)
• .github/workflows/e2e-cloud.yml - Cloud device tests
• .github/workflows/e2e-matrix.yml - Full matrix (all platforms)

Development Mode (NEXT_PUBLIC_USE_DEV_AUTH=true):

export const TEST_USERS = {
  owner: {
    email: '[email protected]',
    password: 'password123',
    role: 'owner',
    userId: 'test-user-owner',
  },
  admin: {
    email: '[email protected]',
    password: 'password123',
    role: 'admin',
    userId: 'test-user-admin',
  },
  member: {
    email: '[email protected]',
    password: 'password123',
    role: 'member',
    userId: 'test-user-member',
  },
  // ... 8 total users
}

Deterministic User IDs: All test users have predictable IDs for assertions.

export const TEST_CHANNELS = {
  general: {
    id: 'test-channel-general',
    name: 'general',
    type: 'public',
  },
  random: {
    id: 'test-channel-random',
    name: 'random',
    type: 'public',
  },
  private: {
    id: 'test-channel-private',
    name: 'private-team',
    type: 'private',
  },
}

import { generateTestId } from './test-helpers'

// Deterministic counter-based IDs
const messageId = generateTestId('message')
// Returns: message-1, message-2, message-3...

// With prefix
const channelId = generateTestId('channel', 'test')
// Returns: test-channel-1, test-channel-2...

• e2e/performance-web.spec.ts - Web performance
• e2e/desktop-only/performance-desktop.spec.ts - Desktop performance
• e2e/mobile/performance.spec.ts - Mobile performance

Location: /e2e/fixtures/test-helpers.ts

/**
 * Deterministic test ID generator
 * Uses incrementing counter instead of Date.now()
 */
export class TestIdGenerator {
  private counters: Map<string, number> = new Map()

  generate(prefix: string = 'test'): string {
    const current = this.counters.get(prefix) || 0
    const next = current + 1
    this.counters.set(prefix, next)
    return `${prefix}-${next}`
  }

  reset(prefix?: string): void {
    if (prefix) {
      this.counters.delete(prefix)
    } else {
      this.counters.clear()
    }
  }
}

// Global instance
export const testIdGenerator = new TestIdGenerator()

// Convenience function
export function generateTestId(prefix: string = 'test'): string {
  return testIdGenerator.generate(prefix)
}

/**
 * Seeded random number generator for deterministic "random" values
 */
export class SeededRandom {
  private seed: number

  constructor(seedString: string) {
    this.seed = this.hashString(seedString)
  }

  private hashString(str: string): number {
    let hash = 0
    for (let i = 0; i < str.length; i++) {
      hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0
    }
    return Math.abs(hash)
  }

  next(): number {
    this.seed = (this.seed * 1103515245 + 12345) & 0x7fffffff
    return this.seed / 0x7fffffff
  }

  nextInt(min: number, max: number): number {
    return Math.floor(this.next() * (max - min + 1)) + min
  }

  choose<T>(array: T[]): T {
    return array[this.nextInt(0, array.length - 1)]
  }
}

/**
 * Smart wait helper - waits for condition with exponential backoff
 */
export async function waitForCondition(
  condition: () => Promise<boolean> | boolean,
  options: {
    timeout?: number
    interval?: number
    description?: string
  } = {}
): Promise<void> {
  const { timeout = 10000, interval = 100, description = 'condition' } = options

  const startTime = Date.now()

  while (Date.now() - startTime < timeout) {
    if (await condition()) {
      return
    }
    await new Promise(resolve => setTimeout(resolve, interval))
  }

  throw new Error(`Timeout waiting for ${description} after ${timeout}ms`)
}

/**
 * Test context with unique IDs per test
 */
export class TestContext {
  private testName: string
  private generator: TestIdGenerator

  constructor(testName: string) {
    this.testName = testName
    this.generator = new TestIdGenerator()
  }

  uniqueId(prefix: string = 'test'): string {
    return this.generator.generate(`${this.testName}-${prefix}`)
  }

  cleanup(): void {
    this.generator.reset()
  }
}

Each test run uses isolated database state:

test.beforeEach(async ({ testContext }) => {
  // Reset database to known state
  await testContext.db.reset()

  // Seed with deterministic test data
  await testContext.db.seed({
    users: TEST_USERS,
    channels: TEST_CHANNELS,
  })
})

test.afterEach(async ({ testContext }) => {
  // Cleanup test data
  await testContext.db.cleanup()
})

test.beforeEach(async ({ page }) => {
  // Clear all storage
  await page.evaluate(() => {
    localStorage.clear()
    sessionStorage.clear()
    indexedDB.databases().then(dbs => {
      dbs.forEach(db => indexedDB.deleteDatabase(db.name))
    })
  })
})

beforeEach(async () => {
  // Reset app to fresh state
  await device.launchApp({
    newInstance: true,
    permissions: { notifications: 'YES', camera: 'YES' },
  })

  // Clear app data
  await MobileTestHelper.clearAppData()
})

• No Date.now() - use generateTestId() instead
• No Math.random() - use SeededRandom instead
• No setTimeout() - use waitForCondition() instead
• No waitForTimeout() - use waitForSelector() / waitForLoadState()
• All external APIs mocked
• Test data isolated and deterministic
• Database reset between tests
• Unique test IDs per test
• Proper cleanup in afterEach
• Network conditions controlled
• Screenshots on failure enabled
• Retry logic for network operations only

Common Causes:

1. Timing differences: CI slower than local

   • ✅ Fix: Increase timeouts for CI: timeout: process.env.CI ? 60000 : 30000

2. Missing environment variables

   • ✅ Fix: Check .github/workflows/*.yml has all required env vars

3. Database not available

   • ✅ Fix: Ensure backend services started in CI

Debugging Steps:

1. Run test 100 times: pnpm test:e2e --repeat-each=100
2. Check for Date.now() or Math.random()
3. Look for waitForTimeout() - replace with proper waits
4. Enable video recording to see what happened
5. Add retries only as last resort

iOS:

# Reset simulator
xcrun simctl shutdown all
xcrun simctl erase all

# Rebuild app
cd platforms/capacitor
rm -rf ios/App/build
pnpm build:ios

Android:

# Reset emulator
adb devices
adb -s <device_id> emu kill

# Clear cache
cd platforms/capacitor/android
./gradlew clean

Electron:

# Rebuild native modules
cd platforms/electron
rm -rf node_modules
pnpm install --force
pnpm rebuild

Tauri:

# Clean Rust build
cd platforms/tauri/src-tauri
cargo clean
cargo build

1. ✅ Create deterministic test helpers
2. ✅ Replace all Date.now() with generateTestId()
3. ✅ Replace all waitForTimeout() with proper waits
4. ✅ Add missing mobile-specific tests (5 files)
5. ✅ Add missing desktop-specific tests (5 files)

1. Visual regression baseline images for all platforms
2. Performance regression tracking
3. Accessibility audit automation
4. Cross-browser screenshot comparison
5. Automated test generation from user flows

• Playwright Documentation
• Detox Documentation
• Appium Documentation
• Electron Testing
• Tauri Testing

Maintained by: nself-chat Team Questions: See /e2e/README.md or create an issue