Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat(dashboard): save screenshot/recording to Downloads in app mode (#40270)

Simon Knott6e3fe1f2e5d0
diff --git a/packages/dashboard/src/dashboard.tsx b/packages/dashboard/src/dashboard.tsx
index 06dcbdbd4b..0de92be817 100644
--- a/packages/dashboard/src/dashboard.tsx
+++ b/packages/dashboard/src/dashboard.tsx
@@ -36,9 +36,26 @@ export const Dashboard: React.FC = () => {
const [frame, setFrame] = React.useState<DashboardChannelEvents['frame']>();
const [picking, setPicking] = React.useState(false);
const [recording, setRecording] = React.useState(false);
- const [screenshotIcon, setScreenshotIcon] = React.useState<'device-camera' | 'clippy'>('device-camera');
+ const [screenshotIcon, setScreenshotIcon] = React.useState<'device-camera' | 'check'>('device-camera');
const [flashTick, setFlashTick] = React.useState(0);
+ const downloadArtifact = React.useCallback(async (id: string) => {
+ const appMode = window.matchMedia('(display-mode: standalone)').matches
+ || (window as any).__dashboardAppModeForTest === true;
+ if (appMode)
+ return await client!.saveAndReveal({ id });
+
+ const a = document.createElement('a');
+ a.href = `/artifact/${encodeURIComponent(id)}`;
+ a.style.display = 'none';
+ document.body.appendChild(a);
+ try {
+ a.click();
+ } finally {
+ a.remove();
+ }
+ }, [client]);
+
const displayRef = React.useRef<HTMLImageElement>(null);
const screenRef = React.useRef<HTMLDivElement>(null);
const toolbarRef = React.useRef<HTMLDivElement>(null);
@@ -298,9 +315,9 @@ export const Dashboard: React.FC = () => {
if (!client)
return;
if (recording) {
- const { path } = await client.stopRecording();
- await client.reveal({ path });
+ const { id } = await client.stopRecording();
setRecording(false);
+ await downloadArtifact(id);
} else {
await client.startRecording();
setRecording(true);
@@ -310,16 +327,15 @@ export const Dashboard: React.FC = () => {
</ToolbarButton>
<ToolbarButton
className='screenshot'
- title='Copy screenshot to clipboard'
+ title='Take screenshot'
icon={screenshotIcon}
disabled={!ready}
onClick={async () => {
if (!client)
return;
- const screenshot = await client.screenshot();
- const blob = await (await fetch('data:image/png;base64,' + screenshot)).blob();
- await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })]);
- setScreenshotIcon('clippy');
+ const { id } = await client.screenshot();
+ await downloadArtifact(id);
+ setScreenshotIcon('check');
setTimeout(() => setScreenshotIcon('device-camera'), 3000);
}}
/>
diff --git a/packages/dashboard/src/dashboardChannel.ts b/packages/dashboard/src/dashboardChannel.ts
index 3f82ec25ca..54cd26b8bb 100644
--- a/packages/dashboard/src/dashboardChannel.ts
+++ b/packages/dashboard/src/dashboardChannel.ts
@@ -45,7 +45,7 @@ export interface DashboardChannel {
closeSession(params: { browser: string }): Promise<void>;
deleteSessionData(params: { browser: string }): Promise<void>;
setVisible(params: { visible: boolean }): Promise<void>;
- reveal(params: { path: string }): Promise<void>;
+ saveAndReveal(params: { id: string }): Promise<void>;
navigate(params: { url: string }): Promise<void>;
back(): Promise<void>;
@@ -60,8 +60,8 @@ export interface DashboardChannel {
pickLocator(): Promise<void>;
cancelPickLocator(): Promise<void>;
startRecording(): Promise<void>;
- stopRecording(): Promise<{ path: string }>;
- screenshot(): Promise<string>;
+ stopRecording(): Promise<{ id: string }>;
+ screenshot(): Promise<{ id: string }>;
on<K extends keyof DashboardChannelEvents>(event: K, listener: (params: DashboardChannelEvents[K]) => void): void;
off<K extends keyof DashboardChannelEvents>(event: K, listener: (params: DashboardChannelEvents[K]) => void): void;
diff --git a/packages/playwright-core/src/tools/dashboard/dashboardApp.ts b/packages/playwright-core/src/tools/dashboard/dashboardApp.ts
index 89a918d122..3fa98c7ba1 100644
--- a/packages/playwright-core/src/tools/dashboard/dashboardApp.ts
+++ b/packages/playwright-core/src/tools/dashboard/dashboardApp.ts
@@ -35,6 +35,7 @@ type RevealOptions = { sessionName?: string; workspaceDir?: string };
async function startDashboardServer(options: { port?: number; host?: string; reveal?: RevealOptions } = {}): Promise<{ url: string; reveal: (options: RevealOptions) => void }> {
const httpServer = new HttpServer();
const dashboardDir = libPath('vite', 'dashboard');
+ const artifacts = new Map<string, string>();
const connections = new Set<DashboardConnection>();
let currentReveal: RevealOptions = options.reveal ?? {};
@@ -42,13 +43,28 @@ async function startDashboardServer(options: { port?: number; host?: string; rev
httpServer.createWebSocket(() => {
let connection: DashboardConnection;
// eslint-disable-next-line prefer-const
- connection = new DashboardConnection(() => connections.delete(connection));
+ connection = new DashboardConnection(() => connections.delete(connection), artifacts);
if (currentReveal.sessionName)
connection.revealSession(currentReveal.sessionName, currentReveal.workspaceDir);
connections.add(connection);
return connection;
}, 'ws');
+ httpServer.routePrefix('/artifact/', (request: http.IncomingMessage, response: http.ServerResponse) => {
+ const pathname = new URL(request.url!, `http://${request.headers.host}`).pathname;
+ const id = decodeURIComponent(pathname.substring('/artifact/'.length));
+ const artifactPath = artifacts.get(id);
+ if (!artifactPath) {
+ response.statusCode = 404;
+ response.end();
+ return true;
+ }
+ // we're not deleting the artifact on purpose, so that the user can restart the download from the omnibox
+ return httpServer.serveFile(request, response, artifactPath, {
+ 'Content-Disposition': `attachment; filename="${path.basename(artifactPath)}"`,
+ });
+ });
+
httpServer.routePrefix('/', (request: http.IncomingMessage, response: http.ServerResponse) => {
const pathname = new URL(request.url!, `http://${request.headers.host}`).pathname;
const filePath = pathname === '/' ? 'index.html' : pathname.substring(1);
diff --git a/packages/playwright-core/src/tools/dashboard/dashboardController.ts b/packages/playwright-core/src/tools/dashboard/dashboardController.ts
index b13c2173b0..0a5740ab5e 100644
--- a/packages/playwright-core/src/tools/dashboard/dashboardController.ts
+++ b/packages/playwright-core/src/tools/dashboard/dashboardController.ts
@@ -17,11 +17,13 @@
import path from 'path';
import os from 'os';
import fs from 'fs';
+import crypto from 'crypto';
import { execFile } from 'child_process';
import { eventsHelper } from '@utils/eventsHelper';
import { connectToBrowserAcrossVersions } from '../utils/connect';
import { serverRegistry } from '../../serverRegistry';
import { createClientInfo } from '../cli-client/registry';
+import { resolveDashboardDownloadsDir } from './dashboardDownloads';
import type * as api from '../../..';
import type { Transport } from '@utils/httpServer';
@@ -51,11 +53,13 @@ export class DashboardConnection implements Transport {
private _visible = true;
private _pendingReveal: { sessionName: string; workspaceDir?: string } | undefined;
- _recordingDir: string;
+ _artifactDir: string;
+ _artifacts: Map<string, string>;
- constructor(onclose: () => void) {
+ constructor(onclose: () => void, artifacts: Map<string, string>) {
this._onclose = onclose;
- this._recordingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'playwright-recordings-'));
+ this._artifactDir = fs.mkdtempSync(path.join(os.tmpdir(), 'playwright-dashboard-'));
+ this._artifacts = artifacts;
}
onconnect() {
@@ -159,18 +163,21 @@ export class DashboardConnection implements Transport {
this._pushTabs();
}
- async reveal(params: { path: string }) {
- switch (os.platform()) {
- case 'darwin':
- execFile('open', ['-R', params.path]);
- break;
- case 'win32':
- execFile('explorer', ['/select,', params.path]);
- break;
- case 'linux':
- execFile('xdg-open', [path.dirname(params.path)]);
- break;
- }
+ async saveAndReveal(params: { id: string }) {
+ const source = this._artifacts.get(params.id);
+ if (!source)
+ throw new Error(`Unknown artifact id: ${params.id}`);
+ this._artifacts.delete(params.id);
+ const destination = path.join(resolveDashboardDownloadsDir(), path.basename(source));
+ // Rename avoids copying bytes when source and destination are on the same
+ // filesystem. On Linux, tmpdir and Downloads may be on different devices —
+ // rename fails with EXDEV, so fall back to copy + unlink.
+ await fs.promises.rename(source, destination).catch(async () => {
+ await fs.promises.copyFile(source, destination);
+ await fs.promises.unlink(source).catch(() => {});
+ });
+ if (!process.env.PLAYWRIGHT_DASHBOARD_DOWNLOADS_DIR_FOR_TEST)
+ revealInFinder(destination);
}
visible(): boolean {
@@ -357,7 +364,6 @@ class AttachedBrowser {
get browserGuid(): string { return this._slot.guid; }
get contextGuid(): string { return this._slot.contextGuid; }
private get _context(): api.BrowserContext { return this._slot.context; }
- private get _descriptor(): BrowserDescriptor { return this._slot.descriptor; }
async init() {
this._contextListeners.push(
@@ -476,28 +482,32 @@ class AttachedBrowser {
const page = this._selectedPage;
if (!page)
return;
- const artifactsDir = this._descriptor.browser.launchOptions.artifactsDir ?? this._owner._recordingDir;
- this._recordingPath = path.join(artifactsDir, `recording-${Date.now()}.webm`);
+ this._recordingPath = path.join(this._owner._artifactDir, `playwright-recording-${Date.now()}.webm`);
if (this._screencastRunning)
await this._restartScreencast(page);
}
- async stopRecording(): Promise<{ path: string }> {
+ async stopRecording(): Promise<{ id: string }> {
const p = this._recordingPath;
if (!p)
throw new Error('No recording in progress');
this._recordingPath = null;
if (this._selectedPage && this._screencastRunning)
await this._restartScreencast(this._selectedPage);
- return { path: p };
+ const id = crypto.randomUUID();
+ this._owner._artifacts.set(id, p);
+ return { id };
}
- async screenshot(): Promise<string> {
+ async screenshot(): Promise<{ id: string }> {
const page = this._selectedPage;
if (!page)
throw new Error('No page selected');
- const buffer = await page.screenshot({ type: 'png' });
- return buffer.toString('base64');
+ const absolutePath = path.join(this._owner._artifactDir, `playwright-screenshot-${Date.now()}.png`);
+ await page.screenshot({ type: 'png', path: absolutePath });
+ const id = crypto.randomUUID();
+ this._owner._artifacts.set(id, absolutePath);
+ return { id };
}
private async _selectPage(page: api.Page) {
@@ -568,6 +578,20 @@ function pageId(p: api.Page): string {
return (p as any)._guid;
}
+function revealInFinder(target: string) {
+ switch (os.platform()) {
+ case 'darwin':
+ execFile('open', ['-R', target]);
+ break;
+ case 'win32':
+ execFile('explorer', ['/select,', target]);
+ break;
+ case 'linux':
+ execFile('xdg-open', [path.dirname(target)]);
+ break;
+ }
+}
+
async function faviconUrl(page: api.Page): Promise<string | undefined> {
const url = page.evaluate(async () => {
const response = await fetch(document.querySelector<HTMLLinkElement>('link[rel~="icon"]')?.href ?? '/favicon.ico');
diff --git a/packages/playwright-core/src/tools/dashboard/dashboardDownloads.ts b/packages/playwright-core/src/tools/dashboard/dashboardDownloads.ts
new file mode 100644
index 0000000000..15d7aee63e
--- /dev/null
+++ b/packages/playwright-core/src/tools/dashboard/dashboardDownloads.ts
@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// Returns the directory the dashboard should drop screenshots and recordings
+// into when running in "app" mode. We use ~/Downloads, which is the physical
+// on-disk path on macOS and Windows (both display a localized name via
+// Finder/Explorer) and on English-locale Linux. Non-English Linux locales
+// localize the directory (~/Téléchargements, ~/下载, ...) via XDG's
+// user-dirs.dirs; we don't parse that file and fall back to a tmpdir subdir
+// there. If that becomes a pain point, read ~/.config/user-dirs.dirs.
+export function resolveDashboardDownloadsDir(): string {
+ const override = process.env.PLAYWRIGHT_DASHBOARD_DOWNLOADS_DIR_FOR_TEST;
+ if (override) {
+ fs.mkdirSync(override, { recursive: true });
+ return override;
+ }
+ const primary = path.join(os.homedir(), 'Downloads');
+ if (fs.existsSync(primary))
+ return primary;
+ const fallback = path.join(os.tmpdir(), 'playwright-dashboard-downloads');
+ fs.mkdirSync(fallback, { recursive: true });
+ return fallback;
+}
diff --git a/tests/mcp/cli-fixtures.ts b/tests/mcp/cli-fixtures.ts
index 673705307d..ecb1abd9e9 100644
--- a/tests/mcp/cli-fixtures.ts
+++ b/tests/mcp/cli-fixtures.ts
@@ -28,6 +28,7 @@ export { expect } from './fixtures';
export const test = baseTest.extend<{
cliEnv: Record<string, string>,
openDashboard: (options?: { cwd?: string, session?: string }) => Promise<Page>,
+ openDashboardApp: (options?: { cwd?: string, session?: string }) => Promise<Page>,
cli: (...args: any[]) => Promise<{
output: string,
error: string,
@@ -55,6 +56,35 @@ export const test = baseTest.extend<{
return page;
});
},
+ openDashboardApp: async ({ cli, playwright, findFreePort, waitForPort }, use) => {
+ const dashboards: { dashboard: Page, browser: import('playwright-core').Browser }[] = [];
+ await use(async (options?: { cwd?: string, session?: string }) => {
+ const debugPort = await findFreePort();
+ const showArgs = options?.session ? [`-s=${options.session}`, 'show'] : ['show'];
+ await cli(...showArgs, {
+ cwd: options?.cwd,
+ env: { PLAYWRIGHT_DASHBOARD_DEBUG_PORT: String(debugPort) },
+ });
+ await waitForPort(debugPort);
+ const browser = await playwright.chromium.connectOverCDP(`http://127.0.0.1:${debugPort}`);
+ const dashboard = browser.contexts()[0].pages()[0];
+ // Headless Chromium with `--app=` does not report display-mode: standalone,
+ // and CDP's Emulation.setEmulatedMedia doesn't honor display-mode features.
+ // Set the test flag directly; downloadArtifact re-reads it on every click.
+ await dashboard.addInitScript(() => { (window as any).__dashboardAppModeForTest = true; });
+ await dashboard.evaluate(() => { (window as any).__dashboardAppModeForTest = true; }).catch(() => {});
+ dashboards.push({ dashboard, browser });
+ return dashboard;
+ });
+ for (const { dashboard, browser } of dashboards) {
+ if (!browser.isConnected())
+ continue;
+ await Promise.all([
+ new Promise(r => browser.on('disconnected', r)),
+ dashboard.close(),
+ ]).catch(e => console.error('Error during dashboard close', e));
+ }
+ },
cli: async ({ mcpBrowser, mcpHeadless, childProcess }, use) => {
const sessions: { name: string, pid: number }[] = [];
await fs.promises.mkdir(test.info().outputPath('.playwright'), { recursive: true });
@@ -84,6 +114,7 @@ function cliEnv() {
return {
PLAYWRIGHT_SERVER_REGISTRY: test.info().outputPath('registry'),
PLAYWRIGHT_DASHBOARD_SETTINGS_FILE_FOR_TEST: test.info().outputPath('dashboard.settings.json'),
+ PLAYWRIGHT_DASHBOARD_DOWNLOADS_DIR_FOR_TEST: test.info().outputPath('dashboard-downloads'),
PLAYWRIGHT_DAEMON_SESSION_DIR: test.info().outputPath('daemon'),
PLAYWRIGHT_SOCKETS_DIR: path.join(test.info().project.outputDir, 'ds', String(test.info().parallelIndex)),
PLAYWRIGHT_CLI_CHANNEL_SCAN_DISABLED_FOR_TEST: '1',
diff --git a/tests/mcp/dashboard.spec.ts b/tests/mcp/dashboard.spec.ts
index be1dc2f985..a5eb4f9373 100644
--- a/tests/mcp/dashboard.spec.ts
+++ b/tests/mcp/dashboard.spec.ts
@@ -131,3 +131,56 @@ test('should pick locator from browser', async ({ cli, server, openDashboard })
const { output } = await pickPromise;
expect(output).toContain(`getByRole('button', { name: 'Submit' })`);
});
+
+test('screenshot triggers a browser download in browser mode', async ({ cli, server, openDashboard }) => {
+ await cli('open', server.EMPTY_PAGE);
+
+ const dashboard = await openDashboard();
+ await dashboard.locator('.sidebar-tab').first().click();
+ await expect(dashboard.locator('img#display')).toBeVisible();
+ await expect(dashboard.locator('.screenshot')).toBeEnabled();
+
+ const [download] = await Promise.all([
+ dashboard.waitForEvent('download'),
+ dashboard.locator('.screenshot').click(),
+ ]);
+ expect(download.suggestedFilename()).toMatch(/^playwright-screenshot-\d+\.png$/);
+});
+
+test('recording triggers a browser download in browser mode', async ({ cli, server, openDashboard }) => {
+ await cli('open', server.EMPTY_PAGE);
+
+ const dashboard = await openDashboard();
+ await dashboard.locator('.sidebar-tab').first().click();
+ await expect(dashboard.locator('img#display')).toBeVisible();
+
+ const recordBtn = dashboard.locator('.recording');
+ await expect(recordBtn).toBeEnabled();
+ await recordBtn.click();
+ await expect(dashboard.locator('.recording-label')).toBeVisible();
+
+ const [download] = await Promise.all([
+ dashboard.waitForEvent('download'),
+ recordBtn.click(),
+ ]);
+ expect(download.suggestedFilename()).toMatch(/^playwright-recording-\d+\.webm$/);
+});
+
+test('screenshot lands in the Downloads dir in app mode', async ({ cli, server, openDashboardApp }, testInfo) => {
+ const downloadsDir = testInfo.outputPath('dashboard-downloads');
+ await fs.promises.mkdir(downloadsDir, { recursive: true });
+
+ await cli('open', server.EMPTY_PAGE);
+
+ const dashboard = await openDashboardApp();
+ await dashboard.locator('.sidebar-tab').first().click();
+ await expect(dashboard.locator('img#display')).toBeVisible();
+ await expect(dashboard.locator('.screenshot')).toBeEnabled();
+
+ await dashboard.locator('.screenshot').click();
+
+ await expect.poll(async () => {
+ const entries = await fs.promises.readdir(downloadsDir).catch(() => []);
+ return entries.filter(f => /^playwright-screenshot-\d+\.png$/.test(f));
+ }).toHaveLength(1);
+});