Principle:Microsoft Playwright Execute Automation Command
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, CLI |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Executing one-off browser automation tasks like taking screenshots, generating PDFs, or opening interactive browser sessions from the command line.
Description
Once a browser is installed and a context is configured, the final step in a CLI-driven browser automation workflow is to execute an automation command. This principle covers the class of operations where the user issues a single command and receives a concrete artifact or interactive session in return, without writing a full test script.
The key automation commands are:
- Open -- Launch a browser window pointed at a URL (or a blank page) for interactive exploration. The console API is exposed for ad-hoc scripting directly in the browser's developer tools.
- Screenshot -- Navigate to a URL, optionally wait for a condition (a CSS selector becoming visible, or a fixed timeout), and capture the visible viewport (or the full scrollable page) as an image file.
- PDF -- Navigate to a URL, wait for a condition, and render the page to a PDF file with a specified paper format. This operation is typically limited to Chromium-based browsers.
These commands share a common execution pattern:
- Launch the browser (headless for screenshot/pdf, headful for open).
- Open a page and navigate to the target URL.
- Apply any wait conditions.
- Perform the capture or present the interactive session.
- Close the browser and write output artifacts.
Browser alias shortcuts provide ergonomic access: instead of open --browser chromium, the user can type cr directly. Similarly, ff and wk are aliases for Firefox and WebKit respectively.
Usage
Apply this principle whenever:
- A user needs a quick visual check of a web page without writing a test script.
- CI pipelines need to capture screenshots or PDFs of deployed pages as part of visual regression or documentation workflows.
- Developers want to interactively explore a page with specific device emulation or geolocation settings.
- A tool needs to convert web content to a static artifact (image or PDF) in a single command.
Theoretical Basis
The execution of a one-off automation command follows a linear pipeline:
FUNCTION executeAutomationCommand(commandType, url, outputPath, options):
1. DETERMINE headless mode:
IF commandType is "screenshot" OR "pdf":
headless = TRUE
ELSE IF commandType is "open":
headless = FALSE
2. LAUNCH browser and CREATE context:
{ browser, context } = launchContext(options, { headless })
3. OPEN page:
page = context.newPage()
IF url is provided:
NORMALIZE url (prepend "http://" if missing, resolve local files)
page.goto(url)
4. APPLY wait conditions (screenshot/pdf only):
IF options.waitForSelector:
page.waitForSelector(options.waitForSelector)
IF options.waitForTimeout:
page.waitForTimeout(options.waitForTimeout)
5. EXECUTE command:
SWITCH commandType:
CASE "open":
EXPOSE console API for interactive use
WAIT for user to close the browser
CASE "screenshot":
page.screenshot({ path: outputPath, fullPage: options.fullPage })
CASE "pdf":
ASSERT engine is Chromium (PDF is engine-specific)
page.pdf({ path: outputPath, format: options.paperFormat })
6. CLOSE page and browser
7. RETURN outputPath (if applicable)
Key design considerations:
- Headless vs. headful -- Screenshot and PDF commands run headless for speed and CI compatibility. The open command runs headful for interactive use.
- Wait strategies -- Waiting for a selector ensures dynamic content has rendered. Waiting for a timeout is a fallback for pages without a reliable selector. Both can be combined.
- Engine constraints -- PDF generation relies on Chromium's built-in print-to-PDF API and is not available in Firefox or WebKit.
- URL normalization -- Local file paths are converted to
file://URLs; bare hostnames receive anhttp://prefix.