openspec-e2e

name	openspec-e2e
description	Playwright E2E test case management conventions for the OpenSpec workflow. Defines test file naming (TC{NNNN}), directory organization by module, TC ID allocation, file independence rules, and sub-assertion patterns. Use when creating, planning, or reviewing E2E test cases within an OpenSpec change.
license	MIT
compatibility	Requires Playwright.
metadata	{"author":"gqcn","version":"1.0"}

OpenSpec E2E Test Case Conventions

Standards for organizing, naming, and writing Playwright E2E test cases in this project.

---

1. Directory Structure

hack/tests/
├── e2e/
│   ├── auth/                        # Module: authentication
│   │   ├── TC0001-login-verification.ts
│   │   └── TC0007-logout.ts
│   ├── admin/                       # Module: admin features
│   │   ├── TC0002-spec-management.ts
│   │   └── TC0003-user-management.ts
│   ├── notebook/                    # Module: notebook lifecycle
│   │   ├── TC0004-create-notebook.ts
│   │   ├── TC0005-jupyterlab-access.ts
│   │   ├── TC0006-training-execution.ts
│   │   ├── TC0008-multi-image-notebook.ts
│   │   └── TC0009-shared-directory.ts
│   └── {module}/                    # New modules follow the same pattern
│       └── TC{NNNN}-{brief-name}.ts
├── fixtures/
│   ├── auth.ts
│   ├── config.ts
│   └── k8s.ts
├── pages/                           # Page Object Model files
│   ├── LoginPage.ts
│   ├── NotebookPage.ts
│   └── ...
└── playwright.config.ts

Key rules:

• Directories under e2e/ are named after feature modules (e.g., auth, notebook, admin).
• Each test case file lives under the module it primarily tests.

---

2. File Naming Convention

Every test file MUST follow the pattern:

TC{NNNN}-{brief-name}.ts

Component	Format	Example
Prefix	TC	TC
ID	4-digit, zero-padded	0001, 0012, 0100
Separator	-	-
Brief name	kebab-case	login-verification
Extension	.ts	.ts

Full examples:

• TC0001-login-verification.ts
• TC0014-bulk-delete-notebooks.ts

Rules:

• One test case (one test.describe block) per file.
• The TC ID is globally unique across all modules.
• No .spec.ts suffix — use plain .ts.

---

3. TC ID Allocation

Before adding a new test case:

1. Scan all existing TC files across every module directory under e2e/:

   find hack/tests/e2e -name 'TC*.ts' | sort
   

2. Identify the highest TC number currently in use.
3. Assign the next sequential number (increment by 1).

Example: If the highest existing file is TC0009-shared-directory.ts, the next test case gets TC0010.

IMPORTANT: TC IDs must never be reused, even if a test case is deleted. Always increment from the historical maximum.

---

4. Test File Template

Each test file follows this structure:

import { test, expect } from '../../fixtures/auth'
import { SomePage } from '../../pages/SomePage'
import { config } from '../../fixtures/config'

test.describe('TC-{N} {Brief Description}', () => {
  // Optional: shared setup
  test.beforeEach(async ({ adminPage }) => {
    // ...
  })

  test('TC-{N}a: {sub-assertion description}', async ({ page }) => {
    // Single focused assertion
  })

  test('TC-{N}b: {sub-assertion description}', async ({ adminPage }) => {
    // Another focused assertion
  })

  test('TC-{N}c: {sub-assertion description}', async ({ adminPage }) => {
    // ...
  })
})

Conventions inside the file:

• The test.describe label uses TC-{N} (no zero-padding) followed by a brief description.
• Sub-tests use TC-{N}{letter}: as prefix (e.g., TC-1a:, TC-1b:).
• When multiple sub-tests are combined into one block, use range notation: TC-{N}a~c:.
• Each sub-test should be focused on a single assertion or closely related assertions.

---

5. Test Independence

Each test file MUST be independently runnable:

• No cross-file dependencies. A test file must not rely on state created by another test file.
• Self-contained setup. If a test needs preconditions (e.g., a logged-in user, a created resource), it must set them up itself via beforeEach, beforeAll, fixtures, or inline setup.
• Clean up after itself. Tests that create resources should clean them up to avoid polluting other tests.
• Runnable in isolation:

  npx playwright test hack/tests/e2e/auth/TC0001-login-verification.ts
  

---

6. Page Object Model (POM)

All page interactions MUST go through Page Object classes in pages/:

import { Page, Locator } from '@playwright/test'

export class SomePage {
  readonly page: Page
  readonly someElement: Locator

  constructor(page: Page) {
    this.page = page
    this.someElement = page.locator('[data-testid="some-element"]')
  }

  async goto() {
    await this.page.goto('/some-path')
    await this.page.waitForLoadState('networkidle')
  }

  async performAction() {
    // Encapsulate complex interactions
  }
}

Rules:

• One POM class per page/feature area.
• POM files live in pages/ (not in e2e/).
• Use data-testid attributes as the primary locator strategy.
• POM methods should return meaningful values or await expected states.

---

7. Fixtures

Shared test setup (authentication, configuration) lives in fixtures/:

• auth.ts — Extends Playwright test with authenticated page fixtures (adminPage, etc.)
• config.ts — Environment-specific configuration (URLs, credentials, timeouts).
• k8s.ts — Kubernetes helpers (pod readiness, exec commands).

Import fixtures instead of @playwright/test directly:

// Correct
import { test, expect } from '../../fixtures/auth'

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

---

8. Mapping TC IDs in OpenSpec Tasks

When writing tasks.md in an OpenSpec change, E2E test tasks MUST reference TC IDs:

### Task 3: E2E — TC0010 Notebook auto-save

- [ ] Create `hack/tests/e2e/notebook/TC0010-notebook-auto-save.ts`
- [ ] Implement TC-10a: file saved after idle timeout
- [ ] Implement TC-10b: save indicator shown in UI
- [ ] Implement TC-10c: content persists after page reload

The TC ID in the task title must match the filename. Sub-assertions (TC-10a, TC-10b) should be listed as sub-items.

---

9. Quick Reference

Item	Convention
File name	TC{NNNN}-{brief-name}.ts
TC ID scope	Global across all modules
Directory	e2e/{module}/
Describe label	TC-{N} {Description}
Sub-test label	TC-{N}{letter}: {description}
Import test/expect	From ../../fixtures/auth
Page interactions	Via POM classes in pages/
Independence	Each file runnable in isolation
ID allocation	Scan max existing → increment by 1