# Recorder for developers

Canonical: https://fairleadhq.com/docs/recorder/developers/

Updated: 2026-10-10
Publication state: published
Product version: Source verified — 52de40a

Agent summary: Use session summaries, HAR requests, console logs, screenshots, and action exports to trace a reported failure and verify a fix.

## Prerequisites

- Access to the issue description and supplied evidence

## Inputs

- Expected and observed behavior, reproduction context, and available attachments or links

## Outputs

- An evidence-backed diagnosis, a regression test, or verification steps for QA

## Limitations

- An issue does not necessarily include every downloaded artifact
- Recorded associations do not prove causality
- Generated scripts need setup and assertions
- Backend correlation needs identifiers captured and logged in the target environment

## Permissions

- Access to the evidence and any application logs used
- Authorization to replay requests or tests against the chosen environment

## Privacy

- Review request data, logs, images, and notes before replaying or sharing them


Investigate a reported failure using the issue description and shared browser evidence.

Use the issue description and files shared from Recorder to investigate a reported failure. Start by comparing what the tester expected with what actually happened. Then use the recorded actions, network requests, console logs, and screenshots to identify the application code to inspect.

Investigate downloaded artifacts with your editor, browser developer tools, existing test tools, and AI Agents.

## Start with the real sample

Download the [sample bug report ZIP](https://fairleadhq.com/downloads/fairlead-recorder-sample-v1.zip) and unzip it. It records **Blocked tag stays after card leaves the Blocked lane** in [Quackban](https://fairleadhq.com/docs/recorder/schema/#about-quackban-and-credits): the tester creates `QB-DEMO sticky Blocked`, moves it into Blocked, then into In progress. The expected result is that leaving Blocked clears the tag; the reported result is that the tag remains.

Read `session.md` first, then `notes.md`, `network.har`, and the screenshots. The [bundle structure](https://fairleadhq.com/docs/recorder/schema/#sample-reproduction-bundle) lists the exact files. Follow the [worked investigation](https://fairleadhq.com/docs/recorder/developers/trace-a-failure/#worked-example-the-sticky-blocked-tag) to connect the recorded action to its request and returned state without installing Recorder or replaying the session.

## Choose the evidence for your question

Use the artifacts shared with the issue:

| Investigation question | Start with | What it helps you establish |
| --- | --- | --- |
| What did the tester do? | `session.md` and `notes.md` | The session context, action sequence, and QA’s observations. Notes are included when the session contains them. |
| What did the application send and receive? | `network.har` | Request URLs, methods, headers, payloads, response status, and captured response content. |
| Where did the browser code fail? | `console.log` | Error messages and stack traces to follow into application code. |
| What did the user see? | Screenshots | The visible state to compare with the expected result and network response. |
| How can I repeat the interaction? | `playwright.spec.ts`, `puppeteer.js`, or `steps.json` | Recorded actions to run in your test environment and develop into a regression test. |

## Reconstruct the attempt

Open `session.md` in a Markdown viewer or editor. Read the description, starting page, browser, and numbered actions alongside the tracker issue. Use `notes.md` for QA’s observations and screenshots for the visible result.

Find the action associated with the reported failure. Its elapsed time is relative to the session’s start time. Use that point to locate the corresponding requests and console entries. Keep the action, request, and visible result together as you investigate.

## Inspect the request and response

Open `network.har` in a HAR viewer, or inspect its JSON in your editor. Locate the relevant request by endpoint, method, and time; then inspect:

1. **Request data:** compare the query parameters and payload with the action and expected application state.
2. **Response:** read the status and captured body to see what the service returned. For GraphQL, inspect operation errors as well as HTTP status.
3. **Application handling:** compare that response with console output and the screenshot. Follow the corresponding request handler or state update in application code.

This helps narrow the investigation: whether the browser sent the intended input, the service returned the expected result, and the UI handled it correctly.

To test a request separately, transfer its method, URL, and relevant payload into your HTTP tooling. Use credentials and data for your chosen test environment, then compare the new response with the captured one. Redacted values need appropriate test values.

## Follow errors into code

Open `console.log` and search around the relevant action or request time. Read the error message and stack together, then follow the referenced code in the application build used for the attempt.

Compare the code’s assumptions with the captured request and response. For example, an exception while reading a response property gives you a specific question: did the service return that property, and does the client handle the returned shape?

Use surrounding log entries to understand the sequence. Check the suspected cause against the evidence before treating a nearby error as the explanation.

## Connect the browser request to server logs

When the evidence contains a correlation identifier that your application logs, search for it in the relevant environment. Match the request URL and time, then follow the server-side processing and error details.

[Backend correlation](https://fairleadhq.com/docs/recorder/session-correlation/) explains the connected-project setup and identifiers. Correlation headers must have been sent and logged for this route to connect the captured browser request to a server log entry.

## Example: a failure with successful requests

The sample contains six HTTP requests, all returning 200. Its summary reports zero console errors, and there is no `console.log` in the ZIP. The bug is in the application state and visible result, so filtering for failed requests would miss it.

| Evidence | Observation | Next investigation step |
| --- | --- | --- |
| `session.md` | Action 20 selects In progress at +32.226 seconds. | Find the move request just after that action. |
| `network.har` | The POST at `04:43:56.539Z` sends the card ID and `status: "in_progress"`, with no `blocked` field. | Inspect the lane-change handler and its state-update rules. |
| `network.har` and `notes.md` | The following board response has `status: "in_progress"`; the blocked value remains the same as after entering Blocked, which QA identifies as `true`. | Compare the response fields with the agreed rule for clearing the flag. |
| `screenshots/003-area.png` | The card still has a red Blocked badge. The crop does not include the lane heading. | Use the action and response to establish the lane, and the image to establish the visible badge. |

This narrows the investigation to how lane changes and the blocked flag interact. It does not establish which application function needs changing. The [detailed walkthrough](https://fairleadhq.com/docs/recorder/developers/trace-a-failure/#worked-example-the-sticky-blocked-tag) includes exact HAR paths and a local inspection command.

## Turn the recorded actions into a regression test

Open the supplied Playwright or Puppeteer script in your test project, or import `steps.json` into Chrome DevTools Recorder. Review the recorded sequence against the issue’s reproduction steps.

Set up the application environment, authentication, and test data. Adapt locators where needed and add assertions for the expected result. For this sample, assert that the moved card is in In progress and no longer shows a Blocked badge. The supplied script only performs actions; see the [sample test adaptation](https://fairleadhq.com/docs/recorder/developers/playwright-export/#adapt-the-sample-recording).

Run the test against the affected behavior and then the fix. Keep the assertion that distinguishes the two. Share the fix or build reference and the expected result with QA for verification.

## Investigate with a coding agent

Give the agent the issue description, relevant artifacts, and application code with a focused task. For example: “Trace the sticky Blocked tag through the supplied HAR and notes, inspect the lane-change handler, and propose a regression test for clearing the badge when the card leaves Blocked.”

Ask it to cite the request, log entry, or action behind each finding and distinguish observations from hypotheses. Review the proposed change and test against the same evidence.

## Related investigation guides

- [Trace an action to a failure](https://fairleadhq.com/docs/recorder/developers/trace-a-failure/) and [inspect GraphQL and streaming traffic](https://fairleadhq.com/docs/recorder/developers/graphql-and-streams/).
- [Reproduce a request](https://fairleadhq.com/docs/recorder/developers/reproduce-a-request/).
- [Build a reliable automated test](https://fairleadhq.com/docs/recorder/developers/reliable-automated-tests/).
- [Prepare evidence for coding agents](https://fairleadhq.com/docs/recorder/developers/agent-handoff/).

The export guides start from the generated file already present in the handoff: [Playwright](https://fairleadhq.com/docs/recorder/developers/playwright-export/), [Puppeteer](https://fairleadhq.com/docs/recorder/developers/puppeteer-export/), and [Chrome DevTools Recorder](https://fairleadhq.com/docs/recorder/developers/devtools-export/).

## Inspect and share evidence

Start with [Inspect a shared artifact bundle](https://fairleadhq.com/docs/recorder/developers/artifact-bundle/). Use the focused guides for [recorded actions](https://fairleadhq.com/docs/recorder/developers/action-evidence/), [network requests](https://fairleadhq.com/docs/recorder/developers/network-evidence/), [console evidence](https://fairleadhq.com/docs/recorder/developers/console-evidence/), [screenshots](https://fairleadhq.com/docs/recorder/developers/image-evidence/), or [environment and timing](https://fairleadhq.com/docs/recorder/developers/performance-evidence/) when that source becomes decisive.

Before handing evidence to another person or tool, [review the supplied files for sensitive data](https://fairleadhq.com/docs/recorder/developers/review-evidence/). Refer to [report structure and artifact formats](https://fairleadhq.com/docs/recorder/schema/) for field meanings and file relationships, and [capture support and limits](https://fairleadhq.com/docs/recorder/developers/capture-support/) when evidence is missing or incomplete.

For agents reading these guides, use the [Markdown version](https://fairleadhq.com/docs/recorder/developers.md), [documentation index](https://fairleadhq.com/llms.txt), or [full documentation corpus](https://fairleadhq.com/llms-full.txt).