Skip to main content

class: Tracing

Added in: v1.12

API for collecting and saving copilotbrowser traces. copilotbrowser traces can be opened in Trace Viewer after copilotbrowser script runs.

note

You probably want to enable tracing in your config file instead of using context.tracing.

The context.tracing API captures browser operations and network activity, but it doesn't record test assertions (like expect calls). We recommend enabling tracing through copilotbrowser Test configuration, which includes those assertions and provides a more complete trace for debugging test failures.

Start recording a trace before performing actions. At the end, stop tracing and save it to a file.

const browser = await chromium.launch();
const context = await browser.newContext();
await context.tracing.start({ screenshots: true, snapshots: true });
const page = await context.newPage();
await page.goto('https://copilotbrowser.dev');
expect(page.url()).toBe('https://copilotbrowser.dev');
await context.tracing.stop({ path: 'trace.zip' });
Browser browser = chromium.launch();
BrowserContext context = browser.newContext();
context.tracing().start(new Tracing.StartOptions()
  .setScreenshots(true)
  .setSnapshots(true));
Page page = context.newPage();
page.navigate("https://copilotbrowser.dev");
context.tracing().stop(new Tracing.StopOptions()
  .setPath(Paths.get("trace.zip")));
browser = await chromium.launch()
context = await browser.new_context()
await context.tracing.start(screenshots=True, snapshots=True)
page = await context.new_page()
await page.goto("https://copilotbrowser.dev")
await context.tracing.stop(path = "trace.zip")
browser = chromium.launch()
context = browser.new_context()
context.tracing.start(screenshots=True, snapshots=True)
page = context.new_page()
page.goto("https://copilotbrowser.dev")
context.tracing.stop(path = "trace.zip")
using var copilotbrowser = await copilotbrowser.CreateAsync();
var browser = await copilotbrowser.Chromium.LaunchAsync();
await using var context = await browser.NewContextAsync();
await context.Tracing.StartAsync(new()
{
  Screenshots = true,
  Snapshots = true
});
var page = await context.NewPageAsync();
await page.GotoAsync("https://copilotbrowser.dev");
await context.Tracing.StopAsync(new()
{
  Path = "trace.zip"
});

async method: Tracing.start​

Added in: v1.12

Start tracing.

note

You probably want to enable tracing in your config file instead of using Tracing.start.

The context.tracing API captures browser operations and network activity, but it doesn't record test assertions (like expect calls). We recommend enabling tracing through copilotbrowser Test configuration, which includes those assertions and provides a more complete trace for debugging test failures.

Usage

await context.tracing.start({ screenshots: true, snapshots: true });
const page = await context.newPage();
await page.goto('https://copilotbrowser.dev');
expect(page.url()).toBe('https://copilotbrowser.dev');
await context.tracing.stop({ path: 'trace.zip' });
context.tracing().start(new Tracing.StartOptions()
  .setScreenshots(true)
  .setSnapshots(true));
Page page = context.newPage();
page.navigate("https://copilotbrowser.dev");
context.tracing().stop(new Tracing.StopOptions()
  .setPath(Paths.get("trace.zip")));
await context.tracing.start(screenshots=True, snapshots=True)
page = await context.new_page()
await page.goto("https://copilotbrowser.dev")
await context.tracing.stop(path = "trace.zip")
context.tracing.start(screenshots=True, snapshots=True)
page = context.new_page()
page.goto("https://copilotbrowser.dev")
context.tracing.stop(path = "trace.zip")
using var copilotbrowser = await copilotbrowser.CreateAsync();
var browser = await copilotbrowser.Chromium.LaunchAsync();
await using var context = await browser.NewContextAsync();
await context.Tracing.StartAsync(new()
{
  Screenshots = true,
  Snapshots = true
});
var page = await context.NewPageAsync();
await page.GotoAsync("https://copilotbrowser.dev");
await context.Tracing.StopAsync(new()
{
  Path = "trace.zip"
});

option: Tracing.start.name​

Added in: v1.12

  • name <string>

If specified, intermediate trace files are going to be saved into the files with the given name prefix inside the BrowserType.launch.tracesDir directory specified in BrowserType.launch(). To specify the final trace zip file name, you need to pass path option to Tracing.stop() instead.

option: Tracing.start.screenshots​

Added in: v1.12

  • screenshots <boolean>

Whether to capture screenshots during tracing. Screenshots are used to build a timeline preview.

option: Tracing.start.snapshots​

Added in: v1.12

  • snapshots <boolean>

If this option is true tracing will

  • capture DOM snapshot on every action
  • record network activity

option: Tracing.start.sources​

Added in: v1.17

Languages: JavaScript, C#, Python

  • sources <boolean>

Whether to include source files for trace actions.

option: Tracing.start.sources​

Added in: v1.17

Languages: Java

  • sources <boolean>

Whether to include source files for trace actions. List of the directories with source code for the application must be provided via copilotbrowser_JAVA_SRC environment variable (the paths should be separated by ';' on Windows and by ':' on other platforms).

option: Tracing.start.title​

Added in: v1.17

  • title <string>

Trace name to be shown in the Trace Viewer.

async method: Tracing.startChunk​

Added in: v1.15

Start a new trace chunk. If you'd like to record multiple traces on the same BrowserContext, use Tracing.start() once, and then create multiple trace chunks with Tracing.startChunk() and Tracing.stopChunk().

Usage

await context.tracing.start({ screenshots: true, snapshots: true });
const page = await context.newPage();
await page.goto('https://copilotbrowser.dev');

await context.tracing.startChunk();
await page.getByText('Get Started').click();
// Everything between startChunk and stopChunk will be recorded in the trace.
await context.tracing.stopChunk({ path: 'trace1.zip' });

await context.tracing.startChunk();
await page.goto('http://example.com');
// Save a second trace file with different actions.
await context.tracing.stopChunk({ path: 'trace2.zip' });
context.tracing().start(new Tracing.StartOptions()
  .setScreenshots(true)
  .setSnapshots(true));
Page page = context.newPage();
page.navigate("https://copilotbrowser.dev");

context.tracing().startChunk();
page.getByText("Get Started").click();
// Everything between startChunk and stopChunk will be recorded in the trace.
context.tracing().stopChunk(new Tracing.StopChunkOptions()
  .setPath(Paths.get("trace1.zip")));

context.tracing().startChunk();
page.navigate("http://example.com");
// Save a second trace file with different actions.
context.tracing().stopChunk(new Tracing.StopChunkOptions()
  .setPath(Paths.get("trace2.zip")));
await context.tracing.start(screenshots=True, snapshots=True)
page = await context.new_page()
await page.goto("https://copilotbrowser.dev")

await context.tracing.start_chunk()
await page.get_by_text("Get Started").click()
# Everything between start_chunk and stop_chunk will be recorded in the trace.
await context.tracing.stop_chunk(path = "trace1.zip")

await context.tracing.start_chunk()
await page.goto("http://example.com")
# Save a second trace file with different actions.
await context.tracing.stop_chunk(path = "trace2.zip")
context.tracing.start(screenshots=True, snapshots=True)
page = context.new_page()
page.goto("https://copilotbrowser.dev")

context.tracing.start_chunk()
page.get_by_text("Get Started").click()
# Everything between start_chunk and stop_chunk will be recorded in the trace.
context.tracing.stop_chunk(path = "trace1.zip")

context.tracing.start_chunk()
page.goto("http://example.com")
# Save a second trace file with different actions.
context.tracing.stop_chunk(path = "trace2.zip")
using var copilotbrowser = await copilotbrowser.CreateAsync();
var browser = await copilotbrowser.Chromium.LaunchAsync();
await using var context = await browser.NewContextAsync();
await context.Tracing.StartAsync(new()
{
  Screenshots = true,
  Snapshots = true
});
var page = await context.NewPageAsync();
await page.GotoAsync("https://copilotbrowser.dev");

await context.Tracing.StartChunkAsync();
await page.GetByText("Get Started").ClickAsync();
// Everything between StartChunkAsync and StopChunkAsync will be recorded in the trace.
await context.Tracing.StopChunkAsync(new()
{
  Path = "trace1.zip"
});

await context.Tracing.StartChunkAsync();
await page.GotoAsync("http://example.com");
// Save a second trace file with different actions.
await context.Tracing.StopChunkAsync(new()
{
  Path = "trace2.zip"
});

option: Tracing.startChunk.title​

Added in: v1.17

  • title <string>

Trace name to be shown in the Trace Viewer.

option: Tracing.startChunk.name​

Added in: v1.32

  • name <string>

If specified, intermediate trace files are going to be saved into the files with the given name prefix inside the BrowserType.launch.tracesDir directory specified in BrowserType.launch(). To specify the final trace zip file name, you need to pass path option to Tracing.stopChunk() instead.

async method: Tracing.group​

Added in: v1.49

caution

Use test.step instead when available.

Creates a new group within the trace, assigning any subsequent API calls to this group, until Tracing.groupEnd() is called. Groups can be nested and will be visible in the trace viewer.

Usage

// use test.step instead
await test.step('Log in', async () => {
  // ...
});
// All actions between group and groupEnd
// will be shown in the trace viewer as a group.
page.context().tracing().group("Open copilotbrowser.dev > API");
page.navigate("https://dayour.github.io/copilotbrowser/");
page.getByRole(AriaRole.LINK, new Page.GetByRoleOptions().setName("API")).click();
page.context().tracing().groupEnd();
# All actions between group and group_end
# will be shown in the trace viewer as a group.
page.context.tracing.group("Open copilotbrowser.dev > API")
page.goto("https://dayour.github.io/copilotbrowser/")
page.get_by_role("link", name="API").click()
page.context.tracing.group_end()
# All actions between group and group_end
# will be shown in the trace viewer as a group.
await page.context.tracing.group("Open copilotbrowser.dev > API")
await page.goto("https://dayour.github.io/copilotbrowser/")
await page.get_by_role("link", name="API").click()
await page.context.tracing.group_end()
// All actions between GroupAsync and GroupEndAsync
// will be shown in the trace viewer as a group.
await Page.Context.Tracing.GroupAsync("Open copilotbrowser.dev > API");
await Page.GotoAsync("https://dayour.github.io/copilotbrowser/");
await Page.GetByRole(AriaRole.Link, new() { Name = "API" }).ClickAsync();
await Page.Context.Tracing.GroupEndAsync();

param: Tracing.group.name​

Added in: v1.49

  • name <string>

Group name shown in the trace viewer.

option: Tracing.group.location​

Added in: v1.49

  • location ?<Object>
    • file <string>
    • line ?<int>
    • column ?<int>

Specifies a custom location for the group to be shown in the trace viewer. Defaults to the location of the Tracing.group() call.

async method: Tracing.groupEnd​

Added in: v1.49

Closes the last group created by Tracing.group().

async method: Tracing.stop​

Added in: v1.12

Stop tracing.

option: Tracing.stop.path​

Added in: v1.12

  • path <path>

Export trace into the file with the given path.

async method: Tracing.stopChunk​

Added in: v1.15

Stop the trace chunk. See Tracing.startChunk() for more details about multiple trace chunks.

option: Tracing.stopChunk.path​

Added in: v1.15

  • path <path>

Export trace collected since the last Tracing.startChunk() call into the file with the given path.