diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f231ca..f7477d7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,11 @@ License: see LICENSE in the repository root. # Changelog +## Unreleased + +- Accept a `metadata` function in the Cypress `registerTemplateCoverage` options. It is called once per test, and its fields are added to the record without replacing the record's own fields, as the Playwright `metadata` option already does. +- Keep custom `metadata` passed to `withTemplateCoverage` through `templateCoverageOptions`. The fixture used to replace it with the test identity fields, which still take precedence. + ## 2.0.1 - Publish under `@magelens/magento-template-coverage` with the same CLI and exports. Existing versions remain available under the previous scope. diff --git a/README.md b/README.md index 227e9f1..0d0946a 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,12 @@ const { registerTemplateCoverage } = require('@magelens/magento-template-coverag registerTemplateCoverage({ outputDir: '.template-coverage' }); ``` +To add fields to each record, such as an ID of the current test attempt, pass `metadata`, a function called once per test in `afterEach`. Its fields precede the record's own fields, which they cannot replace. The Playwright adapters accept a `metadata` object in the same way; with `withTemplateCoverage`, pass it per test through the `templateCoverageOptions` fixture, for example `test.use({templateCoverageOptions: {outputDir: '.template-coverage', metadata: {attempt: 'id'}}})`. Its `spec`, `test`, `retry`, `project` and `worker` fields always describe the running test. + +```js +registerTemplateCoverage({ outputDir: '.template-coverage', metadata: () => ({ attempt: currentAttemptId() }) }); +``` + For Playwright, extend your existing test fixture before using its `page` or `context`: ```js diff --git a/cypress/support.js b/cypress/support.js index 0a5dfcf..452688f 100644 --- a/cypress/support.js +++ b/cypress/support.js @@ -7,7 +7,10 @@ const { observeTemplates } = require('../lib/browser'); const { observeExecution } = require('../lib/execution'); -function registerTemplateCoverage({ outputDir = '.template-coverage' } = {}) { +// `metadata` is called once per test attempt in afterEach; its fields are added to the record, +// for example to identify the attempt. The record's own fields cannot be replaced. +function registerTemplateCoverage({ outputDir = '.template-coverage', metadata } = {}) { + if (metadata !== undefined && typeof metadata !== 'function') throw new TypeError('metadata must be a function'); let collector; let execution; let ids = new Set(); @@ -52,7 +55,10 @@ function registerTemplateCoverage({ outputDir = '.template-coverage' } = {}) { if (collector) collector.flush(); const recordId = globalThis.crypto.randomUUID?.() || `${Date.now()}-${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`; + const extra = metadata ? metadata() : {}; + if (extra === null || typeof extra !== 'object' || Array.isArray(extra)) throw new TypeError('metadata must return an object'); const record = { + ...extra, schemaVersion: 2, recordId, spec: Cypress.spec.relative, diff --git a/playwright/index.js b/playwright/index.js index fa58259..a0c0e77 100644 --- a/playwright/index.js +++ b/playwright/index.js @@ -127,8 +127,9 @@ function withTemplateCoverage(test, options = {}) { finally { if (browser.newContext === wrapped) browser.newContext = newContext; } }, {scope: 'worker'}], context: async ({context, templateCoverageOptions}, use, testInfo) => { + // Custom metadata, such as a test attempt ID, is kept; the test identity fields cannot be replaced. const coverage = await registerTemplateCoverage(context, {...templateCoverageOptions, - metadata: {spec: testInfo.file, test: testInfo.titlePath, retry: testInfo.retry, + metadata: {...templateCoverageOptions.metadata, spec: testInfo.file, test: testInfo.titlePath, retry: testInfo.retry, project: testInfo.project.name, worker: testInfo.workerIndex}}); try { await use(context); } finally { await coverage.stop(); } } diff --git a/test/cypress-support.test.js b/test/cypress-support.test.js new file mode 100644 index 0000000..e9cc346 --- /dev/null +++ b/test/cypress-support.test.js @@ -0,0 +1,48 @@ +// SPDX-FileCopyrightText: MageLens +// SPDX-License-Identifier: MIT +// License: see LICENSE in the repository root. + +'use strict'; + +const test = require('node:test'); +const assert = require('node:assert/strict'); + +// Runs the Cypress adapter's afterEach with stand-ins for the Cypress globals and returns the written record. +function writtenRecord(options) { + const hooks = {}; + const writes = []; + globalThis.Cypress = {on() {}, spec: {relative: 'cypress/e2e/cart.cy.js'}, currentTest: {titlePath: ['cart', 'adds a product']}}; + globalThis.beforeEach = hook => { hooks.beforeEach = hook; }; + globalThis.afterEach = hook => { hooks.afterEach = hook; }; + globalThis.cy = {then: (_options, callback) => callback(), writeFile: (file, contents) => writes.push([file, JSON.parse(contents)])}; + try { + delete require.cache[require.resolve('../cypress/support')]; + require('../cypress/support').registerTemplateCoverage(options); + hooks.afterEach.call({currentTest: {currentRetry: () => 1}}); + assert.equal(writes.length, 1); + assert.match(writes[0][0], /^out\/.+\.mtc$/); + return writes[0][1]; + } finally { + for (const name of ['Cypress', 'beforeEach', 'afterEach', 'cy']) delete globalThis[name]; + } +} + +test('Cypress records identify the test without metadata', () => { + const record = writtenRecord({outputDir: 'out'}); + assert.deepEqual({...record, recordId: null}, {schemaVersion: 2, recordId: null, spec: 'cypress/e2e/cart.cy.js', + test: ['cart', 'adds a product'], retry: 1, ids: [], hits: {}, references: []}); +}); + +test('Cypress metadata adds fields to each record without replacing its own', () => { + let calls = 0; + const record = writtenRecord({outputDir: 'out', metadata: () => ({attempt: `attempt-${++calls}`, retry: 7, schemaVersion: 1})}); + assert.equal(calls, 1); + assert.equal(record.attempt, 'attempt-1'); + assert.equal(record.retry, 1); + assert.equal(record.schemaVersion, 2); +}); + +test('Cypress metadata must be a function returning an object', () => { + assert.throws(() => writtenRecord({outputDir: 'out', metadata: {attempt: 'a'}}), /metadata must be a function/); + assert.throws(() => writtenRecord({outputDir: 'out', metadata: () => null}), /metadata must return an object/); +}); diff --git a/test/playwright/metadata.spec.js b/test/playwright/metadata.spec.js new file mode 100644 index 0000000..852b321 --- /dev/null +++ b/test/playwright/metadata.spec.js @@ -0,0 +1,29 @@ +// SPDX-FileCopyrightText: MageLens +// SPDX-License-Identifier: MIT +// License: see LICENSE in the repository root. + +'use strict'; + +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const {test: base, expect} = require('@playwright/test'); +const {withTemplateCoverage} = require('../../playwright'); + +const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mtc-metadata-')); +const test = withTemplateCoverage(base); +test.use({templateCoverageOptions: {outputDir, metadata: {attempt: 'attempt-1', spec: 'replaced', retry: 9}}}); +test.afterAll(() => fs.rmSync(outputDir, {recursive: true, force: true})); + +test('the fixture writes its record when the context closes', async ({page}) => { + await page.setContent('
Page
'); +}); + +test('custom metadata reaches the record through the fixture without replacing the test identity', () => { + const [file] = fs.readdirSync(outputDir); + const record = JSON.parse(fs.readFileSync(path.join(outputDir, file), 'utf8')); + expect(record.attempt).toBe('attempt-1'); + expect(record.spec).toBe(__filename); + expect(record.retry).toBe(0); + expect(record.test.at(-1)).toBe('the fixture writes its record when the context closes'); +});