Debugging Test Failures with Video, Network Traces, and Playwright Traces

When a check fails, you need to know why, where, and how it happened. supaguard provides high-fidelity "Deep Debugging Traces" to answer these questions instantly—no log diving or guesswork required.

The Debugging Dashboard

Click on any failure in the supaguard dashboard to open the Incident Review. This view consolidates three critical sources of truth:

1. Video Recording

Watch exactly what happened during the test execution.

• Why it's useful: Spot visual bugs, layout shifts, or modal popups that obscured a button
• Control: Pause, scrub, and change playback speed (0.5×, 1×, 2×)
• Retention: Available for 7 days (Hacker) or 30 days (Startup+)

[!TIP] Start with the video. In most cases, watching the 10-30 second recording immediately reveals the root cause—a cookie banner covering a button, a loading spinner that never resolved, or a page that simply failed to render.

2. Network Trace (HAR)

Inspect every HTTP request made during the session.

• Why it's useful: Identify if a specific API call failed (e.g., a 500 error from /api/login) or if a large asset slowed down the page load
• Filter: Filter by request type (XHR, Image, CSS, Font, etc.)
• Timing: See waterfall timing for each request to pinpoint bottlenecks

Key things to look for in the network trace:

3. Playwright Trace

Step-by-step execution path of the test script.

• Why it's useful: Pinpoint the exact line of code where the assertion failed
• Context: See "Before" and "After" DOM snapshots for every action (click, fill, navigate)
• Timeline: Visual timeline of all actions with durations

Common Failure Scenarios

"Element not found" / "Locator timeout"

Symptom: The test timed out waiting for an element.

Diagnosis steps:

1. Watch the video — did the page render at all?
2. Check if a modal, cookie banner, or overlay covered the target element
3. Check if the page layout changed (e.g., element moved below the fold)
4. Verify the selector still matches the current DOM

Common fixes:

// If a cookie banner blocks interaction, dismiss it first
const cookieBanner = page.getByRole("button", { name: "Accept" });
if (await cookieBanner.isVisible({ timeout: 3000 }).catch(() => false)) {
  await cookieBanner.click();
}

"Timeout exceeded"

Symptom: The page took too long to load.

Diagnosis steps:

1. Check the Network tab for slow API calls (>5s response time)
2. Look for large assets blocking the page load
3. Check if the server returned a valid response at all
4. Verify the URL is correct (typos, redirects)

Common fixes:

• Increase the navigation timeout for slow pages
• Use waitForLoadState('domcontentloaded') instead of 'load' for SPAs
• Add explicit waits for critical API responses

// Wait for a specific API response before asserting
await page.waitForResponse(
  (resp) => resp.url().includes("/api/dashboard") && resp.status() === 200
);

"Assertion failed"

Symptom: Expected "Welcome User" but got "Login Failed" or different text.

Diagnosis: This is likely a genuine application bug, not a test issue.

1. Check the Playwright trace for the exact assertion that failed
2. Verify the expected value is still correct
3. Check if the API returned an error (visible in Network tab)
4. If the text changed intentionally, update the assertion

SSL / Certificate Errors

Symptom: ERR_CERT_DATE_INVALID or NET::ERR_CERT_AUTHORITY_INVALID.

Diagnosis: Your SSL certificate is expired or misconfigured.

1. Check the certificate expiry date
2. Verify the certificate chain is complete
3. This is usually a real issue — alert your DevOps team

[!CAUTION] Do not ignore SSL errors in monitoring. An expired certificate will block all real users from accessing your site.

Authentication Failures

Symptom: Login succeeds locally but fails in monitoring.

Common causes:

• Test credentials were rotated
• IP-based rate limiting blocking monitoring IPs
• MFA enabled on the test account
• Session tokens expired

Fix: Use environment variables for credentials, whitelist supaguard IPs via firewall allowlisting, and use a dedicated test account without MFA.

Debugging Decision Tree

When a check fails, follow this sequence:

1. Watch the video → Is there a visible problem? (80% of issues caught here)
2. Check the network trace → Did an API call fail? Is the page slow?
3. Open the Playwright trace → Which specific action or assertion failed?
4. Check Smart Retry results → Did it fail from multiple regions? (If only one region, likely transient)
5. Review failure classification → Is it Critical, Degraded, or a soft failure?

Next Steps

• Configuring Alerts — Get notified the right way
• Smart Retries — How supaguard confirms real failures
• Failure Classification — Understanding severity levels
• Troubleshooting — Comprehensive issue resolution guide