qa-engineer（质量保证工程师）

QA Engineer Skill

Analyze recent code changes in anytype-ts, map them to testable user-facing behavior, and generate Playwright E2E tests in the ../anytype-desktop-suite repository.

When to Use

Activate this skill when:

• After implementing a new feature or modifying existing functionality
• After editor/component changes that affect user interactions
• The user explicitly asks to add tests for recent changes
• After completing a task referenced in CLAUDE.md's "QA Engineer" section

Principles

1. Change-driven — Only test what actually changed, don't generate tests for untouched code
2. User-facing — Focus on observable behavior, not implementation details
3. Compatible — Follow the existing test patterns in anytype-desktop-suite exactly
4. Minimal — One test file per feature area, don't over-test
5. Translation-aware — Always use translation keys, never hardcoded UI text

Process

Phase 1: Analyze Changes

1. Identify what changed — Run git diff against the base branch (or recent commits) to see modified files
2. Classify changes — Determine which changes are user-facing vs internal refactoring
3. Map to features — Connect code changes to testable user flows:

- Component changes → UI interactions to verify - Store changes → State transitions to test - Menu/popup changes → Open/close/interact flows - Editor changes → Block creation, editing, selection - API changes → Data flow and error handling

Skip internal-only changes (type refactors, utility extractions, pure style changes) that have no user-facing impact.

Phase 2: Research Existing Coverage

1. Check existing tests — Search ../anytype-desktop-suite/tests/ for tests that already cover the changed feature area
2. Check existing page objects — Search ../anytype-desktop-suite/src/pages/ for page objects that interact with affected components
3. Check test plans — Search ../anytype-desktop-suite/specs/ for existing plans covering the area
4. Identify gaps — Determine what's not yet covered

Phase 3: Create Test Plan

Write a test plan in ../anytype-desktop-suite/specs/ following this format:

# Feature Area — Test Plan

**Source changes:** List of changed files in anytype-ts
**Date:** YYYY-MM-DD

## Prerequisites
- Seed: `tests/seed.spec.ts` (creates account, opens vault)
- Any additional setup needed

### 1. Test Group Name
**Seed:** `tests/seed.spec.ts`

#### 1.1 Scenario Name
**Steps:**
1. Step description
2. Step description
**Expected:** What should happen

#### 1.2 Another Scenario
...

Phase 4: Generate Test Files

Create test files in ../anytype-desktop-suite/tests/ following these strict conventions:

File Structure

// spec: specs/plan-name.md
// seed: tests/seed.spec.ts

import { test, expect } from '../../src/fixtures';
import { restartGrpcServer } from '../../src/helpers/test-server';
// Import relevant page objects
import { SidebarPage } from '../../src/pages/main/sidebar.page';

test.describe('Feature Area', () => {
  test.describe.configure({ mode: 'serial' });

  test.beforeAll(async () => {
    await restartGrpcServer();
  });

  test('should do the expected behavior', async ({ page, translations }) => {
    const sidebar = new SidebarPage(page, translations);
    await sidebar.waitForReady();

    // Step: Description of what we're doing
    await page.getByText(translations.someTranslationKey).click();

    // Verify: Expected outcome
    await expect(page.locator('#some-element')).toBeVisible();
  });
});

Rules

1. Translations — Always use translations.keyName for UI text. Look up keys in ../anytype-ts/dist/lib/json/lang/en-US.json or ../anytype-ts/src/json/text.json
2. Page Objects — Use existing page objects from ../anytype-desktop-suite/src/pages/. Create new ones only if needed
3. Waits — Use await expect(locator).toBeVisible() or waitFor({state: 'visible'}). Never use setTimeout, networkidle, or fixed delays
4. Selectors — Prefer role-based > test ID > text > CSS selectors
5. Isolation — Each test file restarts gRPC server in beforeAll. Tests in a file can share state with serial mode
6. Naming — File names are kebab-case matching the feature: feature-name.spec.ts
7. Directory — Place in a subdirectory matching the feature area: tests/editor/, tests/blocks/, etc.

Phase 5: Create Page Objects (if needed)

If the changed feature needs new page interactions not covered by existing page objects, create a new page object:

import { BasePage } from '../base.page';

export class FeaturePage extends BasePage {
  // Locators
  get someButton() {
    return this.page.locator('#some-button');
  }

  get someText() {
    return this.page.getByText(this.t('translationKey'));
  }

  // Actions
  async waitForReady() {
    await this.someButton.waitFor({ state: 'visible' });
  }

  async doSomething() {
    await this.someButton.click();
    await expect(this.someText).toBeVisible();
  }
}

Page objects go in ../anytype-desktop-suite/src/pages/ in the appropriate subdirectory.

Phase 6: Output Summary

After generating tests, provide a summary:

## QA Engineer Summary

### Changes Analyzed
- file1.tsx — description of change
- file2.tsx — description of change

### Tests Generated
- `tests/feature/scenario-name.spec.ts` — what it tests
- `specs/feature-plan.md` — test plan

### New Page Objects
- `src/pages/main/feature.page.ts` — (if created)

### Coverage Notes
- What's covered by new tests
- What's NOT covered and why (e.g., requires manual testing, backend-only change)

### Run Tests

cd ../anytype-desktop-suite && npm test -- tests/feature/scenario-name.spec.ts

Finding Translation Keys

To map UI text to translation keys:

1. Search ../anytype-ts/src/json/text.json for the English text
2. The key is the JSON property name (e.g., "authSelectSignup": "Create new vault" → use translations.authSelectSignup)
3. For dynamic text with parameters, check how the component calls translate() with substitution params

Finding Selectors

To find stable selectors for elements:

1. Search the component source in ../anytype-ts/src/ts/component/ for id=, data-, className
2. Check for block IDs: blocks typically have #block-{id} selectors
3. Check for menu IDs: menus use #menu{Type} pattern
4. Check for popup IDs: popups use #popup{Type} pattern
5. The sidebar uses #sidebarPage{Section} pattern

Test Areas Mapping

What NOT to Test

• Pure TypeScript type changes
• Internal utility refactors with no UI impact
• CSS-only changes (unless they affect element visibility/layout)
• Backend (anytype-heart) changes — those have their own tests
• Build/config changes