studio-desktop/.cursor/rules/integration-testing.mdc

---
description: Integration testing guide for ComfyUI Desktop
globs:
  - tests/integration/**
---

# Integration Testing Guide

This document provides quick reference for writing integration tests. For complete details, refer to [README.md](mdc:tests/integration/README.md).

## Quick Start

- Framework: Playwright + TypeScript for Electron testing
- Location: `/tests/integration/`
- Environment: Requires `COMFYUI_ENABLE_VOLATILE_TESTS=1` or CI environment
- Import fixtures from `testExtensions.ts`, not raw Playwright

## Test Projects

- `install`: Fresh install tests (no pre-existing state)
- `post-install-setup`: Sets up an installed app state
- `post-install`: Tests requiring an installed app
- `post-install-teardown`: Cleanup after post-install tests

## Available Fixtures

```typescript
import { expect, test } from '../testExtensions';

// Core fixtures
app: TestApp                    // Electron application
window: Page                    // Main Playwright page

// UI Component fixtures  
installWizard: TestInstallWizard
serverStart: TestServerStart
installedApp: TestInstalledApp
troubleshooting: TestTroubleshooting
graphCanvas: TestGraphCanvas

// Utility
attachScreenshot: (name) => Promise<void>
```

## Common Patterns

### Basic Test Structure
```typescript
import { expect, test } from '../testExtensions';

test('should do something', async ({ window, installWizard }) => {
  await installWizard.clickGetStarted();
  await expect(window).toHaveScreenshot('screenshot.png');
});
```

### Simulating Failures
```typescript
// TestEnvironment provides error simulation
await app.testEnvironment.breakInstallPath();
await app.testEnvironment.breakVenv();
await app.testEnvironment.breakServerStart();
// All automatically restored after test
```

### Mocking Native Dialogs
```typescript
await app.app.evaluate((electron, path) => {
  electron.dialog.showOpenDialog = async () => ({
    canceled: false,
    filePaths: [path]
  });
}, selectedPath);
```

## Key Classes

- `TestApp`: Manages Electron process and test environment
- `TestEnvironment`: File system state and error simulation
- `TestInstallWizard`: Installation flow navigation
- `TestInstalledApp`: Post-install app state
- `TestServerStart`: Server startup monitoring
- `TestTroubleshooting`: Error recovery UI

## Running Tests

```bash
# Set environment variable
export COMFYUI_ENABLE_VOLATILE_TESTS=1

# Run all integration tests
pnpm test:e2e

# Run specific test
pnpm playwright test tests/integration/install/installWizard.spec.ts

# Update screenshots
pnpm test:e2e:update
```

## Best Practices

1. Always import from `testExtensions`, not raw Playwright
2. Use fixture classes instead of raw locators
3. Leverage TestEnvironment for state manipulation
4. Trust auto-cleanup via Symbol.asyncDispose
5. Mark slow tests with `test.slow()`
6. Add screenshots for visual regression
7. Mock native dialogs when needed
8. Check CI behavior with `process.env.CI`

For complete documentation including all test classes, methods, and detailed examples, see [README.md](mdc:tests/integration/README.md).