Recording
Keep a record of what happened. Traces go to ~/.browsercontrol/recordings, snapshots to ~/.browsercontrol/snapshots, and tests to ~/.browsercontrol/generated_tests; see Configuration to move them.
| Tool | Does | Returns |
|---|---|---|
start_recording | Start recording the browser session as a Playwright trace. The trace will be saved when stop_recording is called. Also restarts the action log, so export_test() afterwards covers exactly this recording. | text |
stop_recording | Stop recording and save the session trace. | text |
export_test | Turn the actions taken so far into a replayable Playwright test file. | text |
take_snapshot | Take a named snapshot (screenshot + HTML) for later reference. | text |
list_recordings | List all saved recordings and snapshots. | text |
start_recording
Start recording the browser session as a Playwright trace. The trace will be saved when stop_recording is called. Also restarts the action log, so export_test() afterwards covers exactly this recording.
start_recording(name: str = '')Returns text only.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | str | "" | Optional name for the recording (default: timestamp) |
Starts a Playwright trace and restarts the action log, so export_test afterwards covers exactly this recording. Without a name, a timestamp is used.
→ start_recording("checkout")
Recording started: checkout.zip
Call stop_recording() when done.stop_recording
Stop recording and save the session trace.
stop_recording()Returns text only.
Saves the trace and returns its path and the command to open it.
Recording saved: /home/me/.browsercontrol/recordings/checkout.zip
View with: npx playwright show-trace /home/me/.browsercontrol/recordings/checkout.zipexport_test
Turn the actions taken so far into a replayable Playwright test file.
export_test(name: str = '', language: str = 'python', clear: bool = False)Returns text only.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | str | "" | Test name and file name (default: timestamp) |
language | str | "python" | "python" (pytest-playwright) or "typescript" (@playwright/test) |
clear | bool | False | Empty the action log afterwards, to start the next test fresh |
Writes the actions so far (since the session started, or since start_recording) as a test file, and returns its path, the command to run it, and the code. language is python (pytest-playwright, test_<name>.py) or typescript (@playwright/test, <name>.spec.ts). clear=True empties the action log afterwards.
def test_checkout(page: Page) -> None:
page.goto("https://shop.test/")
page.get_by_role("textbox", name="Email", exact=True).fill("ada@example.com")
page.get_by_label("Password", exact=True).fill(os.environ["BC_SECRET_1"])
page.once("dialog", lambda dialog: dialog.accept())
page.get_by_role("button", name="Pay", exact=True).click()
expect(page.get_by_text("Order confirmed").first).to_be_visible()Elements are located by test id, role and name, label, placeholder, or text, falling back to a CSS path, each checked against the live page. Covers navigation, clicks, typing, keys, selects, checkboxes, uploads, drags, scrolls, waits for text, dialog answers, and request mocks. Typed passwords become BC_SECRET_n environment variables. Review the file before committing.
take_snapshot
Take a named snapshot (screenshot + HTML) for later reference.
take_snapshot(name: str = '')Returns text only.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | str | "" | Optional name for the snapshot (default: timestamp) |
Saves a PNG screenshot and the page's HTML (with BrowserControl's markers removed) under the given name. Without a name, a timestamp is used.
list_recordings
List all saved recordings and snapshots.
list_recordings()Returns text only.
Lists recent traces and snapshots with their paths.
