Playwright is a powerful testing framework, but its HTML reports can feel bare-bones for complex projects. Wouldn't it be nice to display metadata such as commit messages, author details, or links to CI builds right in the report header? Here's how to achieve that and some deeper insights into Playwright's capabilities.
Understanding Playwright Metadata
The Playwright documentation mentions a metadata field for configuration:
import { defineConfig } from '@playwright/test';
export default defineConfig({
metadata: 'acceptance tests',
});
At the time of writing (Playwright v1.49), it states:
Metadata that will be put directly into the test report serialized as JSON
But there's a catch: adding this configuration won't show any metadata in the report. If you're using TypeScript, you'll also see an error for the provided example:
Type 'string' is not assignable to type 'Metadata'.
Clearly, the documentation is outdated, but metadata in reports is indeed possible.
The Real Metadata Configuration
After diving into Playwright’s source code, I discovered the actual fields supported by the HTML report:
export type Metainfo = {
'revision.id'?: string;
'revision.author'?: string;
'revision.email'?: string;
'revision.subject'?: string;
'revision.timestamp'?: number | Date;
'revision.link'?: string;
'ci.link'?: string;
'timestamp'?: number;
};
Only these fields can be displayed. Let’s configure them in playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
reporter: 'html',
metadata: {
'revision.id': 'adcb0c51debdbe96a6a836e2ead9d40a859f6438',
'revision.author': 'John Smith',
'revision.email': 'john.smith@gmail.com',
'revision.subject': 'Acceptance tests',
'revision.timestamp': Date.now(),
'revision.link': 'https://github.com/microsoft/playwright/pull/12734',
'ci.link': 'https://github.com/microsoft/playwright/actions/workflows/tests_primary.yml',
'timestamp': Date.now(),
},
});
After running tests, the HTML report header displays this metadata beautifully.
Automating Metadata Population
Manually filling metadata fields isn't practical, especially in dynamic environments like CI/CD pipelines. Automating this process ensures accurate and consistent metadata without manual effort.
Third-Party packages
To automate the process, you can utilize any third-party package that extracts Git commit information. This is a straightforward approach, let's proceed to the second option that is more interesting.
Leveraging Playwright’s Hidden Plugin System
One of the most intriguing discoveries about Playwright is its hidden plugin system. While not officially documented, it provides a way to extend Playwright's capabilities through custom plugins.
I've got this insight while looking as the test of Playwright itself. Playwright supports a hidden configuration field "@playwright/test", where you can define plugins.
Here’s an example of enabling the gitCommitInfo plugin:
import { defineConfig } from '@playwright/test';
import { gitCommitInfo } from 'playwright/lib/plugins';
export default defineConfig({
reporter: 'html',
// @ts-expect-error
'@playwright/test': {
plugins: [gitCommitInfo()]
},
});
What Does the gitCommitInfo Plugin Do?
This plugin extracts Git commit details and populates metadata fields in the HTML report, including:
- Commit hash
- Commit message
- Author name and email
- Timestamp
Additionally, when run in CI/CD environments, the plugin can automatically populate fields using standard environment variables like GITHUB_SHA or CI_COMMIT_SHA.
After enabling the plugin and running tests, I've got the following report with metadata automatically filled:
Other Plugins
I was curious, are there any other hidden plugins in Playwright?
In the plugins directory there is only one more plugin - webServerPlugin. It allows to start and stop built-in web server when running tests. In fact, when you define config.webServer option, this plugin is used under the hood. So the Plugin system is internally used in Playwright, although is not documented for public usage.
The plugin system was introduced in earlier versions of Playwright, but was hidden as some point. Unfortunately, there are no plans to expose it as of now.
Using a Custom Function for Metadata
If you'd rather auto-fill metadata without relying on plugins, you can do so with a custom function. I've adapted the gitStatusFromCLI() function from the gitCommitInfo plugin, making it usable independently:
import { spawnSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
const GIT_OPERATIONS_TIMEOUT_MS = 1500;
export const gitStatusFromCLI = (gitDir = process.cwd()) => {
const separator = `:${randomUUID().slice(0, 4)}:`;
const { status, stdout } = spawnSync(
'git',
['show', '-s', `--format=%H${separator}%s${separator}%an${separator}%ae${separator}%ct`, 'HEAD'],
{ stdio: 'pipe', cwd: gitDir, timeout: GIT_OPERATIONS_TIMEOUT_MS }
);
if (status) return;
const showOutput = stdout.toString().trim();
const [id, subject, author, email, rawTimestamp] = showOutput.split(separator);
let timestamp: number = Number.parseInt(rawTimestamp, 10);
timestamp = Number.isInteger(timestamp) ? timestamp * 1000 : 0;
return {
'revision.id': id,
'revision.author': author,
'revision.email': email,
'revision.subject': subject,
'revision.timestamp': timestamp,
};
};
Usage of the function to populate metadata in the Playwright config:
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { gitStatusFromCLI } from './commitInfo';
export default defineConfig({
reporter: 'html',
metadata: gitStatusFromCLI()
});
After running tests, I've got the same HTML report with filled metadata:
This approach gives you full control over metadata automation without depending on internal Playwright features.
Optimizing for Parallel Tests
Everything looks good, but there is a performance issue with the code above. Could you guess what is the problem?
Playwright runs tests in workers. When each worker starts, it imports Playwright config. If Playwright config performs a heavy operation (like fetching Git data), it will slow down the worker. Moreover, there is no sense to execute the command many times, as it will return the same result.
You can optimize it by executing the metadata function only in the main worker. The main worker can be detected by empty TEST_WORKER_INDEX env variable:
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { gitStatusFromCLI } from './commitInfo';
const isMainWorker = !process.env.TEST_WORKER_INDEX;
export default defineConfig({
reporter: 'html',
metadata: isMainWorker ? gitStatusFromCLI() : undefined,
});
This ensures metadata is populated efficiently without affecting performance.
Conclusion
Adding metadata to Playwright HTML reports is possible, though not well-documented. You can manually configure metadata, leverage the hidden plugin system, or implement a custom solution.
Key Takeaways:
- Metadata fields are limited to specific keys (
revision.id,ci.link, etc.). - Automate metadata with Playwright’s hidden plugins or custom scripts.
- Optimize for parallel tests by executing metadata logic only in the main worker.
Based on the research for the article, I've opened a pull-request to the Playwright repo, proposing documentation improvements for
metadatafield.
Have you tried adding metadata to Playwright reports? Share your experience or challenges in the comments!
Top comments (0)