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
```bash
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

| anytype-ts Area | Test Directory | Page Objects |
|---|---|---|
| `component/block/text.tsx` | `tests/editor/` | `pages/main/editor.page.ts` |
| `component/block/dataview.tsx` | `tests/dataview/` | `pages/main/dataview.page.ts` |
| `component/menu/` | `tests/menus/` | (inline or new page object) |
| `component/popup/` | `tests/popups/` | `pages/components/modal.component.ts` |
| `component/sidebar/` | `tests/sidebar/` | `pages/main/sidebar.page.ts` |
| `component/widget/` | `tests/widgets/` | `pages/main/widget.page.ts` |
| `component/page/main/graph.tsx` | `tests/graph/` | (new page object) |
| `component/page/auth/` | `tests/auth/` | `pages/auth/*.page.ts` |
| `store/` | (test via UI) | (use existing page objects) |

## 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