[Docs]: Improve documentation for metadata

[vitalets]

Page(s)

https://playwright.dev/docs/next/api/class-testconfig#test-config-metadata

Description

1. Current metadata example does not pass TypeScript check:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  metadata: 'acceptance tests',
});

Result:

Type 'string' is not assignable to type 'Metadata'.

2. Documentation should mention the certain fields that are allowed in metadata, e.g.

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
};

[dgozman]

We discussed this issue, and are not sure how to improve it.

[dgozman]

@vitalets We are open to bringing the commit info into the metadata under an option in the config. If that goes public, then we'll definitely document the fields and the html reporter will show them nicely. Would you like to contribute?

[vitalets]

@vitalets We are open to bringing the commit info into the metadata under an option in the config. If that goes public, then we'll definitely document the fields and the html reporter will show them nicely. Would you like to contribute?

Yes, I'm ready to contribute. Could you guide me, how to name / where to place the config option?

[dgozman]

Yes, I'm ready to contribute. Could you guide me, how to name / where to place the config option?

Something like TestConfig.populateGitInfo, and we'll finalize/rename before the release after the API review.

[vitalets]

Something like TestConfig.populateGitInfo, and we'll finalize/rename before the release after the API review.

Ok! When TestConfig.populateGitInfo is enabled, Playwright internally activates GitCommitInfo plugin, that populates metadata?

[dgozman]

Something like TestConfig.populateGitInfo, and we'll finalize/rename before the release after the API review.

Ok! When TestConfig.populateGitInfo is enabled, Playwright internally activates GitCommitInfo plugin, that populates metadata?

Exactly.

[vitalets]

I thought more about it and got some concerns.
We are going to introduce one more test runner option (TestConfig.populateGitInfo) that actually populates another existing option (metadata), with kind of third-party data needed only for specific reporter (html).
Playwright configuration is already rather complex and has many options. Maybe move this option to html reporter itself? Or to GitInfo plugin somehow?
Otherwise, how will the following code behave from the performance perspective - if I enable gitinfo, but don't use html reporter:

export default defineConfig({
  populateGitInfo: true,
  reporter: 'list'
});

@dgozman What do you think?

[dgozman]

We discussed this being an option of the html reporter, but that is not compatible with merge-reports workflow. There is no harm in populating git info without html - any custom reporter can use that data. In fact, json reporter already includes all of the metadata today. Since we do not have plugins in the public api, config option seems like the best solution.

I think we'd recommend to only enable it on CI anyway:

export default defineConfig({
  populateGitInfo: !!process.env.CI,
});

[vitalets]

Created PR: #34329