stably 4.8.9 → 4.10.0

package/dist/stably-plugin/skills/playwright-best-practices/references/annotations.md

@@ -1,526 +0,0 @@
-# Test Annotations & Organization (Tags)
-
-> **"Tags" = "Annotations"**: In Playwright, "tags" and "annotations" refer to the same thing. When someone asks to "add a tag" to a test, they mean adding a Playwright annotation.
-
-## Table of Contents
-
-1. [Adding Tags/Annotations (Recommended)](#adding-tagsannotations-recommended)
-2. [Filtering Tests by Tag](#filtering-tests-by-tag)
-3. [Skip Annotations](#skip-annotations)
-4. [Fixme & Fail Annotations](#fixme--fail-annotations)
-5. [Slow Tests](#slow-tests)
-6. [Test Steps](#test-steps)
-7. [Custom Annotations (Imperative)](#custom-annotations-imperative)
-8. [Conditional Annotations](#conditional-annotations)
-
-## Adding Tags/Annotations (Recommended)
-
-Use the **declarative syntax** to add tags/annotations to tests. This is the cleanest and most readable approach.
-
-### Basic Tag Syntax
-
-```typescript
-// Add a single tag
-test('user can login', {
-  annotation: { type: 'owner', description: 'Jinjing' }
-}, async ({ page }) => {
-  await page.goto('/login');
-  // test code
-});
-
-// Add multiple tags
-test('checkout completes successfully', {
-  annotation: [
-    { type: 'owner', description: 'Jinjing' },
-    { type: 'priority', description: 'P1' },
-    { type: 'feature', description: 'checkout' }
-  ]
-}, async ({ page }) => {
-  await page.goto('/checkout');
-  // test code
-});
-```
-
-### Common Tag Types
-
-| Tag Type | Purpose | Example |
-|----------|---------|---------|
-| `owner` | Test ownership | `{ type: 'owner', description: 'Jinjing' }` |
-| `priority` | Test priority | `{ type: 'priority', description: 'P1' }` |
-| `feature` | Feature area | `{ type: 'feature', description: 'auth' }` |
-| `ticket` | Link to issue | `{ type: 'ticket', description: 'JIRA-123' }` |
-| `smoke` | Smoke test | `{ type: 'smoke', description: '' }` |
-| `regression` | Regression test | `{ type: 'regression', description: '' }` |
-
-### Tags on Describe Blocks
-
-```typescript
-test.describe('Payment flows', {
-  annotation: [
-    { type: 'feature', description: 'payments' },
-    { type: 'owner', description: 'Alice' }
-  ]
-}, () => {
-  test('credit card payment', async ({ page }) => {
-    // inherits annotations from describe block
-  });
-
-  test('paypal payment', async ({ page }) => {
-    // inherits annotations from describe block
-  });
-});
-```
-
-## Filtering Tests by Tag
-
-Run specific tests based on their tags using the `--grep` flag.
-
-### Basic Filtering
-
-```bash
-# Run tests owned by Jinjing
-npx playwright test --grep "@owner:Jinjing"
-
-# Run P1 priority tests
-npx playwright test --grep "@priority:P1"
-
-# Run smoke tests
-npx playwright test --grep "@smoke"
-
-# Run tests for a specific feature
-npx playwright test --grep "@feature:checkout"
-```
-
-### Advanced Filtering
-
-```bash
-# Run tests matching multiple criteria (AND)
-npx playwright test --grep "(?=.*@owner:Jinjing)(?=.*@priority:P1)"
-
-# Exclude tests with a tag
-npx playwright test --grep-invert "@slow"
-
-# Combine with file patterns
-npx playwright test tests/checkout/ --grep "@smoke"
-```
-
-### Tag Format in grep
-
-The `--grep` flag matches against the test title AND annotations. Annotations are formatted as `@type:description` or just `@type` if description is empty.
-
-
-
-## Skip Annotations
-
-### Basic Skip
-
-```typescript
-// Skip unconditionally
-test.skip("feature not implemented", async ({ page }) => {
-  // This test won't run
-});
-
-// Skip with reason
-test("payment flow", async ({ page }) => {
-  test.skip(true, "Payment gateway in maintenance");
-  // Test body won't execute
-});
-```
-
-### Conditional Skip
-
-```typescript
-test("webkit-specific feature", async ({ page, browserName }) => {
-  test.skip(browserName !== "webkit", "This feature only works in WebKit");
-
-  await page.goto("/webkit-feature");
-});
-
-test("production only", async ({ page }) => {
-  test.skip(process.env.ENV !== "production", "Only runs against production");
-
-  await page.goto("/prod-feature");
-});
-```
-
-### Skip by Platform
-
-```typescript
-test("windows-specific", async ({ page }) => {
-  test.skip(process.platform !== "win32", "Windows only");
-});
-
-test("not on CI", async ({ page }) => {
-  test.skip(!!process.env.CI, "Skipped in CI environment");
-});
-```
-
-### Skip Describe Block
-
-```typescript
-test.describe("Admin features", () => {
-  test.skip(
-    ({ browserName }) => browserName === "firefox",
-    "Firefox admin bug",
-  );
-
-  test("admin dashboard", async ({ page }) => {
-    // Skipped in Firefox
-  });
-
-  test("admin settings", async ({ page }) => {
-    // Skipped in Firefox
-  });
-});
-```
-
-## Fixme & Fail Annotations
-
-### Fixme - Known Issues
-
-```typescript
-// Mark test as needing fix (skips the test)
-test.fixme("broken after refactor", async ({ page }) => {
-  // Test won't run but is tracked
-});
-
-// Conditional fixme
-test("flaky on CI", async ({ page }) => {
-  test.fixme(!!process.env.CI, "Investigate CI flakiness - ticket #123");
-
-  await page.goto("/flaky-feature");
-});
-```
-
-### Fail - Expected Failures
-
-```typescript
-// Test is expected to fail (runs but expects failure)
-test("known bug", async ({ page }) => {
-  test.fail();
-
-  await page.goto("/buggy-page");
-  // If this passes, the test fails (bug was fixed!)
-  await expect(page.getByText("Working")).toBeVisible();
-});
-
-// Conditional fail
-test("fails on webkit", async ({ page, browserName }) => {
-  test.fail(browserName === "webkit", "WebKit rendering bug #456");
-
-  await page.goto("/render-test");
-  await expect(page.getByTestId("element")).toHaveCSS("width", "100px");
-});
-```
-
-### Difference Between Skip, Fixme, Fail
-
-| Annotation     | Runs? | Use Case                         |
-| -------------- | ----- | -------------------------------- |
-| `test.skip()`  | No    | Feature not applicable           |
-| `test.fixme()` | No    | Known bug, needs investigation   |
-| `test.fail()`  | Yes   | Expected to fail, tracking a bug |
-
-## Slow Tests
-
-### Mark Slow Tests
-
-```typescript
-// Triple the default timeout
-test("large data import", async ({ page }) => {
-  test.slow();
-
-  await page.goto("/import");
-  await page.setInputFiles("#file", "large-file.csv");
-  await page.getByRole("button", { name: "Import" }).click();
-
-  await expect(page.getByText("Import complete")).toBeVisible();
-});
-
-// Conditional slow
-test("video processing", async ({ page, browserName }) => {
-  test.slow(browserName === "webkit", "WebKit video processing is slow");
-
-  await page.goto("/video-editor");
-});
-```
-
-### Custom Timeout
-
-```typescript
-test("very long operation", async ({ page }) => {
-  // Set specific timeout (in milliseconds)
-  test.setTimeout(120000); // 2 minutes
-
-  await page.goto("/long-operation");
-});
-
-// Timeout for describe block
-test.describe("Integration tests", () => {
-  test.describe.configure({ timeout: 60000 });
-
-  test("test 1", async ({ page }) => {
-    // Has 60 second timeout
-  });
-});
-```
-
-## Test Steps
-
-### Basic Steps
-
-```typescript
-test("checkout flow", async ({ page }) => {
-  await test.step("Add item to cart", async () => {
-    await page.goto("/products");
-    await page.getByRole("button", { name: "Add to Cart" }).click();
-  });
-
-  await test.step("Go to checkout", async () => {
-    await page.getByRole("link", { name: "Cart" }).click();
-    await page.getByRole("button", { name: "Checkout" }).click();
-  });
-
-  await test.step("Fill shipping info", async () => {
-    await page.getByLabel("Address").fill("123 Test St");
-    await page.getByLabel("City").fill("Test City");
-  });
-
-  await test.step("Complete payment", async () => {
-    await page.getByLabel("Card").fill("4242424242424242");
-    await page.getByRole("button", { name: "Pay" }).click();
-  });
-
-  await expect(page.getByText("Order confirmed")).toBeVisible();
-});
-```
-
-### Nested Steps
-
-```typescript
-test("user registration", async ({ page }) => {
-  await test.step("Fill registration form", async () => {
-    await page.goto("/register");
-
-    await test.step("Personal info", async () => {
-      await page.getByLabel("Name").fill("John Doe");
-      await page.getByLabel("Email").fill("john@example.com");
-    });
-
-    await test.step("Security", async () => {
-      await page.getByLabel("Password").fill("SecurePass123");
-      await page.getByLabel("Confirm Password").fill("SecurePass123");
-    });
-  });
-
-  await test.step("Submit and verify", async () => {
-    await page.getByRole("button", { name: "Register" }).click();
-    await expect(page.getByText("Welcome")).toBeVisible();
-  });
-});
-```
-
-### Steps with Return Values
-
-```typescript
-test("verify order", async ({ page }) => {
-  const orderId = await test.step("Create order", async () => {
-    await page.goto("/checkout");
-    await page.getByRole("button", { name: "Place Order" }).click();
-
-    // Return value from step
-    return await page.getByTestId("order-id").textContent();
-  });
-
-  await test.step("Verify order details", async () => {
-    await page.goto(`/orders/${orderId}`);
-    await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
-  });
-});
-```
-
-### Step in Page Object
-
-```typescript
-// pages/checkout.page.ts
-export class CheckoutPage {
-  async fillShippingInfo(address: string, city: string) {
-    await test.step("Fill shipping information", async () => {
-      await this.page.getByLabel("Address").fill(address);
-      await this.page.getByLabel("City").fill(city);
-    });
-  }
-
-  async completePayment(cardNumber: string) {
-    await test.step("Complete payment", async () => {
-      await this.page.getByLabel("Card").fill(cardNumber);
-      await this.page.getByRole("button", { name: "Pay" }).click();
-    });
-  }
-}
-```
-
-## Custom Annotations (Imperative)
-
-> **Prefer declarative syntax**: The [declarative approach](#adding-tagsannotations-recommended) above is cleaner. Use imperative annotations only when you need to add them conditionally at runtime.
-
-### Add Annotations Imperatively
-
-```typescript
-test("important feature", async ({ page }, testInfo) => {
-  // Add custom annotation at runtime
-  testInfo.annotations.push({
-    type: "priority",
-    description: "high",
-  });
-
-  testInfo.annotations.push({
-    type: "ticket",
-    description: "JIRA-123",
-  });
-
-  await page.goto("/feature");
-});
-```
-
-### Annotation Fixture
-
-```typescript
-// fixtures/annotations.fixture.ts
-import { test as base, TestInfo } from "@playwright/test";
-
-type AnnotationFixtures = {
-  annotate: {
-    ticket: (id: string) => void;
-    priority: (level: "low" | "medium" | "high") => void;
-    owner: (name: string) => void;
-  };
-};
-
-export const test = base.extend<AnnotationFixtures>({
-  annotate: async ({}, use, testInfo) => {
-    await use({
-      ticket: (id) => {
-        testInfo.annotations.push({ type: "ticket", description: id });
-      },
-      priority: (level) => {
-        testInfo.annotations.push({ type: "priority", description: level });
-      },
-      owner: (name) => {
-        testInfo.annotations.push({ type: "owner", description: name });
-      },
-    });
-  },
-});
-
-// Usage
-test("critical feature", async ({ page, annotate }) => {
-  annotate.ticket("JIRA-456");
-  annotate.priority("high");
-  annotate.owner("Alice");
-
-  await page.goto("/critical");
-});
-```
-
-### Read Annotations in Reporter
-
-```typescript
-// reporters/annotation-reporter.ts
-import { Reporter, TestCase, TestResult } from "@playwright/test/reporter";
-
-class AnnotationReporter implements Reporter {
-  onTestEnd(test: TestCase, result: TestResult) {
-    const ticket = test.annotations.find((a) => a.type === "ticket");
-    const priority = test.annotations.find((a) => a.type === "priority");
-
-    if (ticket) {
-      console.log(`Test linked to: ${ticket.description}`);
-    }
-
-    if (priority?.description === "high" && result.status === "failed") {
-      console.log(`HIGH PRIORITY FAILURE: ${test.title}`);
-    }
-  }
-}
-
-export default AnnotationReporter;
-```
-
-## Conditional Annotations
-
-### Annotation Helper
-
-```typescript
-// helpers/test-annotations.ts
-import { test } from "@playwright/test";
-
-export function skipInCI(reason = "Skipped in CI") {
-  test.skip(!!process.env.CI, reason);
-}
-
-export function skipInBrowser(browser: string, reason: string) {
-  test.beforeEach(({ browserName }) => {
-    test.skip(browserName === browser, reason);
-  });
-}
-
-export function onlyInEnv(env: string) {
-  test.skip(process.env.ENV !== env, `Only runs in ${env}`);
-}
-```
-
-```typescript
-// tests/feature.spec.ts
-import { skipInCI, onlyInEnv } from "../helpers/test-annotations";
-
-test("local only feature", async ({ page }) => {
-  skipInCI("Uses local resources");
-
-  await page.goto("/local-feature");
-});
-
-test("production check", async ({ page }) => {
-  onlyInEnv("production");
-
-  await page.goto("/prod-only");
-});
-```
-
-### Describe-Level Conditions
-
-```typescript
-test.describe("Mobile features", () => {
-  test.beforeEach(({ isMobile }) => {
-    test.skip(!isMobile, "Mobile only tests");
-  });
-
-  test("touch gestures", async ({ page }) => {
-    // Only runs on mobile
-  });
-});
-
-test.describe("Desktop features", () => {
-  test.beforeEach(({ isMobile }) => {
-    test.skip(isMobile, "Desktop only tests");
-  });
-
-  test("hover interactions", async ({ page }) => {
-    // Only runs on desktop
-  });
-});
-```
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern                | Problem                | Solution                         |
-| --------------------------- | ---------------------- | -------------------------------- |
-| Skipping without reason     | Hard to track why      | Always provide description       |
-| Too many skipped tests      | Test debt accumulates  | Review and clean up regularly    |
-| Using skip instead of fixme | Loses intent           | Use fixme for bugs, skip for N/A |
-| Not using steps             | Hard to debug failures | Group logical actions in steps   |
-
-## Related References
-
-- **Test Organization**: See [test-organization.md](test-organization.md) for structuring tests
-- **Debugging**: See [debugging.md](debugging.md) for troubleshooting