Desktop E2E Testing Skill

This skill enables Claude to generate comprehensive end-to-end tests for the complete Desktop Ethereal application, covering UI interactions, system integration, and user workflows.

When to Apply This Skill

Apply this skill when the user:

• Asks to write E2E tests for the complete application
• Asks to test user workflows or complete user journeys
• Mentions Playwright, system testing, or desktop application testing
• Requests UI interaction testing or integration testing
• Wants to improve test coverage for end-to-end scenarios

Do NOT apply when:

• User is asking about unit tests (frontend or backend)
• User is asking about specific component testing
• User is only asking conceptual questions without code context

Quick Reference

Tech Stack

| Tool | Version | Purpose | | ------ | --------- | --------- | | Playwright | 1.40+ | E2E testing framework | | TypeScript | 5.9+ | Test scripting | | Node.js | 18+ | Runtime environment |

Key Commands

# Run all E2E tests
pnpm test:e2e

# Run tests in headed mode
pnpm test:e2e --headed

# Run specific test file
pnpm test:e2e tests/e2e/basic-workflow.spec.ts

# Generate test report
pnpm test:e2e --reporter=html

Test Structure Template

import { test, expect } from '@playwright/test';

test.describe('Desktop Ethereal E2E Tests', () => {
  test.beforeEach(async ({ page }) => {
    // Setup test environment
    await page.goto('/');
    // Wait for application to load
    await page.waitForSelector('[data-testid="ethereal-window"]');
  });

  test.afterEach(async ({ page }) => {
    // Cleanup test environment
    await page.close();
  });

  // User workflow tests (REQUIRED)
  test.describe('Basic User Workflow', () => {
    test('should display ethereal window on startup', async ({ page }) => {
      // Arrange - Application started in beforeEach

      // Act - No action needed, just observing initial state

      // Assert
      await expect(page.locator('[data-testid="ethereal-window"]')).toBeVisible();
      await expect(page.locator('[data-testid="status-display"]')).toContainText('IDLE');
    });

    test('should toggle click-through mode', async ({ page }) => {
      // Arrange
      const enableButton = page.locator('[data-testid="enable-click-through"]');
      const disableButton = page.locator('[data-testid="disable-click-through"]');

      // Act
      await enableButton.click();

      // Assert
      await expect(disableButton).toBeVisible();
      await expect(enableButton).not.toBeVisible();

      // Act
      await disableButton.click();

      // Assert
      await expect(enableButton).toBeVisible();
      await expect(disableButton).not.toBeVisible();
    });
  });

  // System integration tests
  test.describe('System Integration', () => {
    test('should respond to GPU temperature changes', async ({ page }) => {
      // Arrange
      const statusDisplay = page.locator('[data-testid="status-display"]');

      // Act - Simulate GPU temperature event
      await page.evaluate(() => {
        window.dispatchEvent(new CustomEvent('gpu-update', {
          detail: { temperature: 85, utilization: 50 }
        }));
      });

      // Assert
      await expect(statusDisplay).toContainText('OVERHEATING');
      await expect(statusDisplay).toContainText('85°C');
    });
  });

  // UI interaction tests
  test.describe('UI Interactions', () => {
    test('should drag window when not in click-through mode', async ({ page }) => {
      // Arrange
      const windowElement = page.locator('[data-testid="ethereal-window"]');

      // Act
      await windowElement.dragTo(windowElement, {
        targetPosition: { x: 100, y: 100 }
      });

      // Assert
      // Verify window position changed (implementation dependent)
    });
  });
});

Testing Workflow (CRITICAL)

⚠️ Incremental Approach Required

NEVER generate all test files at once. For complex workflows or multi-scenario testing:

1. Analyze & Plan: List all user workflows, order by complexity (simple → complex)
2. Process ONE at a time: Write test → Run test → Fix if needed → Next
3. Verify before proceeding: Do NOT continue to next workflow until current passes

For each workflow:
  ┌────────────────────────────────────────┐
  │ 1. Write test                          │
  │ 2. Run: pnpm test:e2e test-file.spec.ts│
  │ 3. PASS? → Mark complete, next workflow│
  │    FAIL? → Fix first, then continue    │
  │ 4. Check coverage                      │
  └────────────────────────────────────────┘

Complexity-Based Order

Process in this order for multi-workflow testing:

1. 🟢 Basic application startup and visibility
2. 🟢 Simple UI interactions (clicking buttons)
3. 🟡 System event responses
4. 🟡 State transitions
5. 🔴 Complex user workflows
6. 🔴 Cross-feature integration scenarios

Core Principles

1. User-Centric Testing

• Test from the user's perspective
• Focus on complete workflows, not individual components
• Verify observable behavior and user experience

2. Realistic Test Scenarios

• Use realistic data and inputs
• Simulate actual user interactions
• Test common and edge case scenarios

3. Deterministic Tests

• Ensure tests produce consistent results
• Use proper waits and assertions
• Avoid flaky test conditions

4. Descriptive Test Naming

Use should <behavior> when <condition>:

test('should display overheating state when GPU temperature exceeds 80°C')
test('should enable click-through mode when Ctrl+Shift+D is pressed')
test('should animate ethereal when system activity changes')

Required Test Scenarios

Always Required (Core Functionality)

1. Application Startup: Window appears, initial state is correct
2. Basic UI Interaction: Buttons respond to clicks
3. Mode Toggling: Click-through mode can be enabled/disabled
4. Window Movement: Window can be dragged when not in click-through mode

Conditional (When Present)

| Feature | Test Focus | | --------- | ------------ | | System Monitoring | Response to GPU/CPU events | | State Transitions | Correct state changes based on system activity | | Sprite Animation | Animations play correctly for each state | | LLM Integration | Chat functionality works | | Clipboard Monitoring | Response to clipboard changes | | Hotkey Support | Global hotkeys function |

Coverage Goals (Per Workflow)

For each test workflow generated, aim for:

• ✅ 100% workflow coverage
• ✅ 100% user interaction coverage
• ✅ >95% scenario coverage
• ✅ >95% edge case coverage

Desktop-Specific Considerations

Window Management Testing

Test window-specific behaviors:

test('should maintain always-on-top behavior', async ({ page }) => {
  // Test that the window stays on top of other applications
});

test('should respect transparent window properties', async ({ page }) => {
  // Test that transparency works correctly
});

System Integration Testing

Test system-level integrations:

test('should respond to system GPU monitoring events', async ({ page }) => {
  // Simulate GPU temperature events and verify response
  await page.evaluate(() => {
    window.dispatchEvent(new CustomEvent('gpu-update', {
      detail: { temperature: 85, utilization: 75 }
    }));
  });

  await expect(page.locator('[data-testid="status"]')).toContainText('OVERHEATING');
});

Input Method Testing

Test various input methods:

test('should respond to global hotkey Ctrl+Shift+D', async ({ page }) => {
  // Test global hotkey functionality
  await page.keyboard.press('Control+Shift+D');
  // Verify mode changed
});

test('should respond to mouse drag when not click-through', async ({ page }) => {
  // Test window dragging functionality
});

Playwright-Specific Patterns

Page Object Model

Use page objects for maintainable tests:

// tests/e2e/page-objects/EtherealWindow.ts
export class EtherealWindow {
  constructor(private page: Page) {}

  async toggleClickThrough() {
    const enableButton = this.page.locator('[data-testid="enable-click-through"]');
    const disableButton = this.page.locator('[data-testid="disable-click-through"]');

    if (await enableButton.isVisible()) {
      await enableButton.click();
    } else {
      await disableButton.click();
    }
  }

  async getStatus() {
    return await this.page.locator('[data-testid="status-display"]').textContent();
  }
}

// In test file
test('should toggle click-through mode', async ({ page }) => {
  const etherealWindow = new EtherealWindow(page);

  await etherealWindow.toggleClickThrough();
  // ... assertions
});

Custom Assertions

Create custom assertions for complex verifications:

// tests/e2e/utils/assertions.ts
export async function expectEtherealState(page: Page, expectedState: string) {
  const status = await page.locator('[data-testid="status-display"]').textContent();
  expect(status).toContain(expectedState);
}

// In test file
import { expectEtherealState } from '../utils/assertions';

test('should enter overheating state when GPU temp exceeds 80°C', async ({ page }) => {
  // ... trigger GPU event
  await expectEtherealState(page, 'OVERHEATING');
});

Test Data Management

Fixture Data

Use fixtures for consistent test data:

// tests/e2e/fixtures/gpu-events.ts
export const gpuEvents = {
  normal: { temperature: 65, utilization: 30 },
  hot: { temperature: 85, utilization: 75 },
  critical: { temperature: 95, utilization: 90 }
};

// In test file
import { gpuEvents } from '../fixtures/gpu-events';

test('should respond to GPU temperature events', async ({ page }) => {
  await page.evaluate((event) => {
    window.dispatchEvent(new CustomEvent('gpu-update', { detail: event }));
  }, gpuEvents.hot);

  // ... assertions
});

Detailed Guides

For more detailed information, refer to:

• references/workflow.md - Incremental testing workflow (MUST READ for multi-workflow testing)
• references/playwright-patterns.md - Playwright testing patterns and best practices
• references/system-integration.md - System integration testing approaches
• references/ui-interactions.md - UI interaction testing techniques
• references/test-organization.md - Test file organization and structure

Authoritative References

Primary Specification (MUST follow)

• docs/e2e-testing.md - The canonical testing specification for Desktop Ethereal E2E tests.

Reference Examples in Codebase

• tests/e2e/ - E2E test directory (to be created)
• playwright.config.ts - Playwright configuration
• package.json - Test scripts and dependencies

Project Configuration

• playwright.config.ts - Playwright configuration
• tests/e2e/ - E2E test files