Implementation:Microsoft Playwright Codegen CLI

Knowledge Sources	Playwright Playwright Codegen Playwright CLI
Domains	Testing, Code_Generation, CLI
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for launching a browser recording session from the command line, provided by the Playwright library.

Description

The codegen CLI command is the primary entry point for Playwright's test recording functionality. It registers a commander.js subcommand that accepts an optional URL and a set of options controlling the recording session. When invoked, it launches a browser with a configured context, enables the recorder instrumentation, opens the inspector window, and navigates to the provided URL if one is given.

The command is registered using commandWithOpenOptions('codegen [url]', ...), which attaches all the shared browser launch options (browser choice, device emulation, viewport, geolocation, etc.) alongside codegen-specific options like --output, --target, and --test-id-attribute.

The implementation flow is:

Parse CLI arguments via commander.js.
Call launchContext() to create a configured browser context (L562).
Call context._enableRecorder() with recording parameters (L570).
Call openPage() to navigate to the initial URL (L581).
The recording session is now active; the user interacts with the browser while the inspector displays generated code.

Usage

Use this command when you want to:

Start a new test recording session from the terminal.
Generate test code for a specific URL with custom output settings.
Record tests targeting a specific language or framework.
Record using a custom test ID attribute for selector generation.

Code Reference

Source Location

Repository: playwright
File: packages/playwright-core/src/cli/program.ts
Lines: L68-80 (command registration), L559-583 (codegen action handler)

Signature

commandWithOpenOptions('codegen [url]', 'open page and generate code for user actions')
  .option('-o, --output <file name>', 'saves the generated script to a file')
  .option('--target <language>', 'language to generate, one of javascript, playwright-test, python, python-async, python-pytest, csharp, csharp-mstest, csharp-nunit, java, java-junit', 'playwright-test')
  .option('--test-id-attribute <attributeName>', 'use a custom test id attribute name')
  .action(async function(url: string | undefined, options: Options) {
    // ... codegen implementation
  }) -> Promise<void>

Import

// Internal - this is a CLI entry point, not a public API import
// Invoked via: npx playwright codegen [url]
// Or via: playwright codegen [url]

I/O Contract

Inputs

Name	Type	Required	Description
url	string	No	URL to navigate to when opening the browser. If omitted, opens a blank page.
-o, --output	string	No	File path to save the generated script. If omitted, code is only displayed in the inspector.
--target	string	No	Target language for code generation. Defaults to `'playwright-test'`. Options: javascript, playwright-test, python, python-async, python-pytest, csharp, csharp-mstest, csharp-nunit, java, java-junit.
--test-id-attribute	string	No	Custom attribute name used for test ID selectors (e.g., `data-testid`, `data-qa`). Overrides the default test ID attribute.
--browser	string	No	Browser to use: `cr` (Chromium), `ff` (Firefox), or `wk` (WebKit). Inherited from open options.
--device	string	No	Named device to emulate (e.g., "iPhone 13"). Inherited from open options.
--viewport-size	string	No	Viewport dimensions as `width,height`. Inherited from open options.
--color-scheme	string	No	Preferred color scheme: `light` or `dark`. Inherited from open options.
--geolocation	string	No	Geolocation as `latitude,longitude`. Inherited from open options.
--timezone	string	No	Timezone ID (e.g., `America/New_York`). Inherited from open options.
--load-storage	string	No	Path to a JSON file containing saved storage state (cookies, localStorage).
--save-storage	string	No	Path to save storage state to when the browser is closed.

Outputs

Name	Type	Description
Browser window	Visual	Launched browser instance navigated to the specified URL.
Inspector window	Visual	Recorder inspector showing real-time generated code, language tabs, and recording controls.
Output file	File (optional)	If `--output` is specified, the generated script is written to this file path upon completion.
Exit code	number	0 on success, non-zero on error.

Usage Examples

Basic Example

# Record a test for a URL, output to TypeScript test file
npx playwright codegen --output tests/example.spec.ts https://example.com

Advanced Example

# Record a Python pytest test on iPhone 13 emulation
npx playwright codegen \
  --target python-pytest \
  --device "iPhone 13" \
  --output tests/test_mobile.py \
  https://example.com

# Record with custom test ID attribute and saved auth state
npx playwright codegen \
  --test-id-attribute data-qa \
  --load-storage auth.json \
  --output tests/authenticated.spec.ts \
  https://example.com/dashboard

Programmatic Invocation

// The codegen command can also be triggered programmatically
// by enabling the recorder on a browser context:
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headful: true });
  const context = await browser.newContext();
  await context._enableRecorder({
    mode: 'recording',
    language: 'playwright-test',
    outputFile: 'tests/recorded.spec.ts',
  });
  const page = await context.newPage();
  await page.goto('https://example.com');
  // User interacts with the browser...
})();

Related Pages

Implements Principle

Principle:Microsoft_Playwright_Launch_Codegen

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment