testeiya 0.2.0 → 0.3.9

package/skills/playwright-best-practices-skill/debugging/debugging.md

@@ -1,504 +0,0 @@
-# Debugging & Troubleshooting
-
-## Table of Contents
-
-1. [Debug Tools](#debug-tools)
-2. [Trace Viewer](#trace-viewer)
-3. [Identifying Flaky Tests](#identifying-flaky-tests)
-4. [Debugging Network Issues](#debugging-network-issues)
-5. [Debugging in CI](#debugging-in-ci)
-6. [Debugging Authentication](#debugging-authentication)
-7. [Debugging Screenshots](#debugging-screenshots)
-8. [Common Issues](#common-issues)
-9. [Logging](#logging)
-
-## Debug Tools
-
-### Playwright Inspector
-
-```bash
-# Run with inspector
-PWDEBUG=1 npx playwright test
-# Or specific test
-PWDEBUG=1 npx playwright test login.spec.ts
-```
-
-Features:
-
-- Step through test actions
-- Pick locators visually
-- Inspect DOM state
-- Edit and re-run
-
-### Headed Mode
-
-```bash
-# Run with visible browser
-npx playwright test --headed
-
-# Interactive debugging (headed, paused, step-through)
-npx playwright test --debug
-```
-
-You can also set `slowMo` to add an `N` ms delay per action, making test execution easier to follow while debugging.
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  use: {
-    launchOptions: {
-      slowMo: 500,
-    },
-  },
-});
-```
-
-### UI Mode
-
-```bash
-# Interactive test runner
-npx playwright test --ui
-```
-
-Features:
-
-- Watch mode
-- Test timeline
-- DOM snapshots
-- Network logs
-- Console logs
-
-### Debug in Code
-
-```typescript
-test("debug example", async ({ page }) => {
-  await page.goto("/");
-
-  // Pause and open inspector
-  await page.pause();
-
-  // Continue test...
-  await page.click("button");
-});
-```
-
-## Trace Viewer
-
-### Enable Traces
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  use: {
-    trace: "on-first-retry", // Record on retry
-    // trace: 'on',                 // Always record
-    // trace: 'retain-on-failure',  // Keep only failures
-  },
-});
-```
-
-### View Traces
-
-```bash
-# Open trace file
-npx playwright show-trace trace.zip
-
-# From test-results
-npx playwright show-trace test-results/test-name/trace.zip
-```
-
-### Trace Contents
-
-- Screenshots at each action
-- DOM snapshots
-- Network requests/responses
-- Console logs
-- Action timeline
-- Source code
-
-### Programmatic Traces
-
-```typescript
-test("manual trace", async ({ page, context }) => {
-  await context.tracing.start({ screenshots: true, snapshots: true });
-
-  await page.goto("/");
-  await page.click("button");
-
-  await context.tracing.stop({ path: "trace.zip" });
-});
-```
-
-## Identifying Flaky Tests
-
-If a test fails intermittently, it's likely flaky. Quick checks:
-
-| Behavior                               | Likely Cause                  | Next Step                              |
-| -------------------------------------- | ----------------------------- | -------------------------------------- |
-| Fails sometimes, passes other times    | Flaky - timing/race condition | [flaky-tests.md](flaky-tests.md)       |
-| Fails only with multiple workers       | Flaky - parallelism/isolation | [flaky-tests.md](flaky-tests.md)       |
-| Fails only in CI                       | Environment difference        | [CI Debugging](#debugging-in-ci) below |
-| Always fails                           | Bug in test or app            | Debug with tools above                 |
-| Always passes locally, always fails CI | CI-specific issue             | [ci-cd.md](../infrastructure-ci-cd/ci-cd.md)                   |
-
-> **For flaky test detection commands, root cause analysis, and fixing strategies**, see [flaky-tests.md](flaky-tests.md).
-
-## Debugging Network Issues
-
-### Monitor All Requests
-
-```typescript
-test("debug network", async ({ page }) => {
-  const requests: string[] = [];
-  const failures: string[] = [];
-
-  page.on("request", (req) => requests.push(`>> ${req.method()} ${req.url()}`));
-  page.on("requestfinished", (req) => {
-    const resp = req.response();
-    requests.push(`<< ${resp?.status()} ${req.url()}`);
-  });
-  page.on("requestfailed", (req) => {
-    failures.push(`FAILED: ${req.url()} - ${req.failure()?.errorText}`);
-  });
-
-  await page.goto("/dashboard");
-
-  // Log summary
-  console.log("Requests:", requests.length);
-  if (failures.length) console.log("Failures:", failures);
-});
-```
-
-### Wait for Specific API Response
-
-When debugging network-dependent issues, wait for specific API responses instead of arbitrary timeouts.
-
-```typescript
-// Start waiting BEFORE triggering the request
-const responsePromise = page.waitForResponse(
-  (resp) => resp.url().includes("/api/data") && resp.status() === 200,
-);
-await page.getByRole("button", { name: "Load" }).click();
-const response = await responsePromise;
-console.log("Status:", response.status());
-```
-
-> **For comprehensive waiting patterns** (navigation, element state, network, polling), see [assertions-waiting.md](../core/assertions-waiting.md#waiting-strategies).
-
-### Debug Slow Requests
-
-```typescript
-test("find slow requests", async ({ page }) => {
-  page.on("requestfinished", (request) => {
-    const timing = request.timing();
-    const total = timing.responseEnd - timing.requestStart;
-    if (total > 1000) {
-      console.log(`SLOW (${total}ms): ${request.url()}`);
-    }
-  });
-
-  await page.goto("/");
-});
-```
-
-## Debugging in CI
-
-### Simulate CI Locally
-
-```bash
-# Run in headless mode like CI
-CI=true npx playwright test
-
-# Match CI browser versions
-npx playwright install --with-deps
-
-# Run in Docker (same as CI)
-docker run --rm -v $(pwd):/work -w /work \
-  mcr.microsoft.com/playwright:v1.40.0-jammy \
-  npx playwright test
-```
-
-### CI-Specific Configuration
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  // More artifacts in CI for debugging
-  use: {
-    trace: process.env.CI ? "on-first-retry" : "off",
-    video: process.env.CI ? "retain-on-failure" : "off",
-    screenshot: process.env.CI ? "only-on-failure" : "off",
-  },
-
-  // More retries in CI (but investigate failures!)
-  retries: process.env.CI ? 2 : 0,
-});
-```
-
-### Debug CI Environment
-
-```typescript
-test("CI environment check", async ({ page }, testInfo) => {
-  console.log("CI:", process.env.CI);
-  console.log("Project:", testInfo.project.name);
-  console.log("Worker:", testInfo.workerIndex);
-  console.log("Retry:", testInfo.retry);
-  console.log("Base URL:", testInfo.project.use.baseURL);
-
-  // Check viewport
-  const viewport = page.viewportSize();
-  console.log("Viewport:", viewport);
-});
-```
-
-## Debugging Authentication
-
-```typescript
-test("debug auth", async ({ page, context }) => {
-  // Inspect current storage state
-  const storage = await context.storageState();
-  console.log(
-    "Cookies:",
-    storage.cookies.map((c) => c.name),
-  );
-
-  // Check if auth cookies are present
-  const cookies = await context.cookies();
-  const authCookie = cookies.find((c) => c.name.includes("session"));
-  console.log("Auth cookie:", authCookie ? "present" : "MISSING");
-
-  await page.goto("/protected");
-
-  // Check if redirected to login (auth failed)
-  if (page.url().includes("/login")) {
-    console.error("Auth failed - redirected to login");
-    // Save state for inspection
-    await context.storageState({ path: "debug-auth.json" });
-  }
-});
-```
-
-## Debugging Screenshots
-
-### Compare Visual State
-
-```typescript
-test("visual debug", async ({ page }, testInfo) => {
-  await page.goto("/");
-
-  // Screenshot before action
-  await page.screenshot({
-    path: testInfo.outputPath("before.png"),
-    fullPage: true,
-  });
-
-  await page.getByRole("button", { name: "Open Menu" }).click();
-
-  // Screenshot after action
-  await page.screenshot({
-    path: testInfo.outputPath("after.png"),
-    fullPage: true,
-  });
-
-  // Attach to report
-  await testInfo.attach("before", {
-    path: testInfo.outputPath("before.png"),
-    contentType: "image/png",
-  });
-});
-```
-
-### Screenshot Specific Element
-
-```typescript
-test("element screenshot", async ({ page }) => {
-  await page.goto("/");
-
-  const element = page.getByTestId("problem-area");
-
-  // Screenshot just the element
-  await element.screenshot({ path: "element-debug.png" });
-
-  // Highlight element in full page screenshot
-  await element.evaluate((el) => (el.style.border = "3px solid red"));
-  await page.screenshot({ path: "highlighted.png" });
-});
-```
-
-## Common Issues
-
-### Element Not Found
-
-```typescript
-// Debug: Check if element exists
-console.log(await page.getByRole("button").count());
-
-// Debug: Log all buttons
-const buttons = await page.getByRole("button").all();
-for (const button of buttons) {
-  console.log(await button.textContent());
-}
-
-// Debug: Screenshot before action
-await page.screenshot({ path: "debug.png" });
-await page.getByRole("button").click();
-```
-
-### Timeout Issues
-
-```typescript
-// Increase timeout for slow operations
-await expect(page.getByText("Loaded")).toBeVisible({ timeout: 30000 });
-
-// Global timeout increase
-test.setTimeout(60000);
-
-// Check what's blocking
-test("debug timeout", async ({ page }) => {
-  await page.goto("/slow-page");
-
-  // Log network activity
-  page.on("request", (request) => console.log(">>", request.url()));
-  page.on("response", (response) =>
-    console.log("<<", response.url(), response.status()),
-  );
-});
-```
-
-### Selector Issues
-
-```typescript
-// Debug: Highlight element
-await page.getByRole("button").highlight();
-
-// Debug: Evaluate selector in browser console
-// Run in Inspector console:
-// playwright.locator('button').first().highlight()
-
-// Debug: Get element info
-const element = page.getByRole("button");
-console.log("Count:", await element.count());
-console.log("Visible:", await element.isVisible());
-console.log("Enabled:", await element.isEnabled());
-```
-
-### Frame Issues
-
-```typescript
-// Debug: List all frames
-for (const frame of page.frames()) {
-  console.log("Frame:", frame.url());
-}
-
-// Debug: Check if element is in iframe
-const frame = page.frameLocator("iframe").first();
-console.log(await frame.getByRole("button").count());
-```
-
-## Logging
-
-### Capture Browser Console
-
-```typescript
-test("with logging", async ({ page }) => {
-  page.on("console", (msg) => console.log("Browser:", msg.text()));
-  page.on("pageerror", (error) => console.log("Page error:", error.message));
-  await page.goto("/");
-});
-```
-
-> **For comprehensive console error handling** (fail on errors, allowed patterns, fixtures), see [console-errors.md](console-errors.md).
-
-### Custom Test Attachments
-
-```typescript
-test("with attachments", async ({ page }, testInfo) => {
-  // Attach screenshot to report
-  const screenshot = await page.screenshot();
-  await testInfo.attach("screenshot", {
-    body: screenshot,
-    contentType: "image/png",
-  });
-
-  // Attach logs or data
-  await testInfo.attach("logs", {
-    body: "Custom log data",
-    contentType: "text/plain",
-  });
-
-  // Use testInfo for output paths
-  const outputPath = testInfo.outputPath("debug-file.json");
-});
-```
-
-## Troubleshooting Checklist
-
-### By Symptom
-
-| Symptom                                       | Common Causes                                                | Quick Fixes                                                         | Reference                                                                  |
-| --------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| **Element not found**                         | Wrong selector, element not visible, in iframe, timing issue | Check locator with Inspector, wait for visibility, use frameLocator | [locators.md](../core/locators.md), [assertions-waiting.md](../core/assertions-waiting.md) |
-| **Timeout errors**                            | Slow network, heavy page load, waiting for wrong condition   | Increase timeout, wait for specific response, check network tab     | [assertions-waiting.md](../core/assertions-waiting.md)                             |
-| **Flaky tests**                               | Race conditions, shared state, timing dependencies           | See comprehensive flaky test guide                                  | [flaky-tests.md](flaky-tests.md)                                           |
-| **Tests pass locally, fail in CI**            | Environment differences, missing dependencies, timing        | Simulate CI locally, check CI logs, verify environment vars         | [ci-cd.md](../infrastructure-ci-cd/ci-cd.md), [flaky-tests.md](flaky-tests.md)                     |
-| **Slow test execution**                       | Not parallelized, heavy network calls, unnecessary waits     | Enable parallelization, mock APIs, optimize waits                   | [performance.md](../infrastructure-ci-cd/performance.md)                                           |
-| **Selector works in browser but not in test** | Element not attached, wrong context, dynamic content         | Use auto-waiting, check iframe, verify element state                | [locators.md](../core/locators.md)                                                 |
-| **Test fails on retry**                       | Non-deterministic data, external dependencies                | Use test data fixtures, mock external services                      | [fixtures-hooks.md](../core/fixtures-hooks.md)                                     |
-
-### Step-by-Step Debugging Process
-
-1. **Reproduce the issue**
-
-   ```bash
-   # Run with trace enabled
-   npx playwright test tests/failing.spec.ts --trace on
-
-   # If intermittent, run multiple times
-   npx playwright test --repeat-each=10
-   ```
-
-2. **Inspect the failure**
-
-   ```bash
-   # View trace
-   npx playwright show-trace test-results/path-to-trace.zip
-
-   # Run in headed mode to watch
-   npx playwright test --headed
-
-   # Use inspector for step-by-step
-   PWDEBUG=1 npx playwright test
-   ```
-
-3. **Isolate the problem**
-
-   ```typescript
-   // Add debugging points
-   await page.pause();
-
-   // Log element state
-   console.log("Element count:", await page.getByRole("button").count());
-   console.log("Element visible:", await page.getByRole("button").isVisible());
-
-   // Take screenshot at failure point
-   await page.screenshot({ path: "debug.png" });
-   ```
-
-4. **Check related areas**
-   - Network requests: Are API calls completing? (see [Debugging Network Issues](#debugging-network-issues))
-   - Timing: Is auto-waiting working correctly?
-   - State: Is the test isolated? (see [flaky-tests.md](flaky-tests.md))
-   - Environment: Does it work locally but fail in CI? (see [Debugging in CI](#debugging-in-ci))
-
-5. **Apply fix and verify**
-   - Fix the root cause (not just symptoms)
-   - Run multiple times to confirm stability: `--repeat-each=10`
-   - Check related tests aren't affected
-
-## Related References
-
-- **Flaky tests**: See [flaky-tests.md](flaky-tests.md) for comprehensive flaky test guide
-- **Locator issues**: See [locators.md](../core/locators.md) for selector strategies
-- **Waiting problems**: See [assertions-waiting.md](../core/assertions-waiting.md) for waiting patterns
-- **Test isolation**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for fixtures and isolation
-- **CI issues**: See [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) for CI configuration