From c9ddd12834e7cc2fd1ee47cd41d722b205b92123 Mon Sep 17 00:00:00 2001 From: Jean-Yves Moyen Date: Mon, 9 Dec 2024 15:55:39 +0100 Subject: [PATCH] Test utils improvements (#114) * Accept various form of optional commit information * Update documentation --- .changeset/forty-bulldogs-hide.md | 7 +++ docs/review/api/alfa-test-utils.api.md | 3 +- .../docs/usage/reporting/advanced.md | 10 +++-- packages/alfa-test-utils/package.json | 1 + packages/alfa-test-utils/src/report/sip.ts | 22 +++++++--- .../alfa-test-utils/test/report/sip.spec.tsx | 44 +++++++++++++------ yarn.lock | 1 + 7 files changed, 65 insertions(+), 23 deletions(-) create mode 100644 .changeset/forty-bulldogs-hide.md diff --git a/.changeset/forty-bulldogs-hide.md b/.changeset/forty-bulldogs-hide.md new file mode 100644 index 00000000..dc10a210 --- /dev/null +++ b/.changeset/forty-bulldogs-hide.md @@ -0,0 +1,7 @@ +--- +"@siteimprove/alfa-test-utils": minor +--- + +**Added:** `SIP.upload` now also accepts the commit information as an `Option` or `Result`. + +This makes it easier to integrate with the `getCommitInformation` which provides it as a `Result`. diff --git a/docs/review/api/alfa-test-utils.api.md b/docs/review/api/alfa-test-utils.api.md index 1ba2dc91..bec1aa54 100644 --- a/docs/review/api/alfa-test-utils.api.md +++ b/docs/review/api/alfa-test-utils.api.md @@ -13,6 +13,7 @@ import { Flattened } from '@siteimprove/alfa-rules'; import * as json from '@siteimprove/alfa-json'; import { Map as Map_2 } from '@siteimprove/alfa-map'; import { Node } from '@siteimprove/alfa-dom'; +import { Option } from '@siteimprove/alfa-option'; import type { Outcome } from '@siteimprove/alfa-act'; import { Page } from '@siteimprove/alfa-web'; import { Performance as Performance_2 } from '@siteimprove/alfa-performance'; @@ -267,7 +268,7 @@ export namespace SIP { // (undocumented) export interface Options { apiKey?: string; - commitInformation?: CommitInformation; + commitInformation?: CommitInformation | Option | Result; pageTitle?: string | ((page: Page) => string); pageURL?: string | ((page: Page) => string); siteID?: string; diff --git a/packages/alfa-test-utils/docs/usage/reporting/advanced.md b/packages/alfa-test-utils/docs/usage/reporting/advanced.md index 64b3aa92..baa93646 100644 --- a/packages/alfa-test-utils/docs/usage/reporting/advanced.md +++ b/packages/alfa-test-utils/docs/usage/reporting/advanced.md @@ -2,9 +2,13 @@ ## Building a test name -The [`testName` option](./configuration.md#including-a-test-name) can also be a function producing a `string` from basic [git information](https://github.com/Siteimprove/alfa-integrations/blob/main/docs/api/alfa-test-utils.git.md). For example, it can be convenient to name a test after the branch it comes from: +The [`testName` option](./configuration.md#including-a-test-name) can also be a function producing a `string` from basic [commit information](https://github.com/Siteimprove/alfa-integrations/blob/main/docs/api/alfa-test-utils.commitinformation.md). For example, it can be convenient to name a test after the branch it comes from: ```typescript +import { getCommitInformation } from "@siteimprove/alfa-test-utils/git.js"; + +const gitInformation = await getCommitInformation().getOr(undefined); + const pageReportURL = Audit.run(alfaPage, { rules: { include: Rules.aaFilter }, }).then((alfaResult) => { @@ -12,8 +16,8 @@ const pageReportURL = Audit.run(alfaPage, { userName: process.env.SI_USER_NAME, // email address of the user. apiKey: process.env.SI_API_KEY, // API key generated in the platform. siteID: "123456", // Site ID from the Siteimprove Intelligence Platform. - testName: (gitInfo) => - `WCAG 2.2 Level AA conformance test on ${gitInfo.branch}`, + testName: (commit) => + `WCAG 2.2 Level AA conformance test on ${commit.BranchName}`, }); }); ``` diff --git a/packages/alfa-test-utils/package.json b/packages/alfa-test-utils/package.json index 37ab9cf5..d9a49c0a 100644 --- a/packages/alfa-test-utils/package.json +++ b/packages/alfa-test-utils/package.json @@ -50,6 +50,7 @@ "@siteimprove/alfa-predicate": "^0.96.0", "@siteimprove/alfa-refinement": "^0.96.0", "@siteimprove/alfa-rules": "^0.96.0", + "@siteimprove/alfa-selective": "^0.96.0", "@siteimprove/alfa-selector": "^0.96.0", "@siteimprove/alfa-sequence": "^0.96.0", "@siteimprove/alfa-thunk": "^0.96.0", diff --git a/packages/alfa-test-utils/src/report/sip.ts b/packages/alfa-test-utils/src/report/sip.ts index da46206d..d33ee926 100644 --- a/packages/alfa-test-utils/src/report/sip.ts +++ b/packages/alfa-test-utils/src/report/sip.ts @@ -3,7 +3,8 @@ import { Element, Query } from "@siteimprove/alfa-dom"; import { Map } from "@siteimprove/alfa-map"; import { None, Option } from "@siteimprove/alfa-option"; import { Err, Ok } from "@siteimprove/alfa-result"; -import type { Result } from "@siteimprove/alfa-result"; +import { Result } from "@siteimprove/alfa-result"; +import { Selective } from "@siteimprove/alfa-selective"; import type { Thunk } from "@siteimprove/alfa-thunk"; import { Page } from "@siteimprove/alfa-web"; @@ -74,7 +75,9 @@ export namespace SIP { if (missing.length > 0) { return Err.of( - `The following mandatory options are missing: ${missing.join(", ")}` + `The following mandatory option${ + missing.length === 1 ? " is" : "s are" + } missing: ${missing.join(", ")}` ); } @@ -138,7 +141,10 @@ export namespace SIP { /** * Information about the latest commit of a Version Control System. */ - commitInformation?: CommitInformation; + commitInformation?: + | CommitInformation + | Option + | Result; } /** @@ -261,12 +267,16 @@ export namespace SIP { ? title(page()) : title; - const commitInfo = Option.from(options.commitInformation); + const commitInfo = Selective.of(options.commitInformation) + .if(Option.isOption, (info) => info) + .if(Result.isResult, (info) => info.ok()) + .else(Option.from) + .get(); const name = options.testName ?? Defaults.Name; const TestName = - // If the name is a string, using, otherwise call the function on the - // gitInfo, defaulting to the error if any. + // If the name is a string, use it, otherwise call the function on the + // commit info, defaulting to the default name. typeof name === "string" ? name : name !== undefined diff --git a/packages/alfa-test-utils/test/report/sip.spec.tsx b/packages/alfa-test-utils/test/report/sip.spec.tsx index 16a042b1..713d057a 100644 --- a/packages/alfa-test-utils/test/report/sip.spec.tsx +++ b/packages/alfa-test-utils/test/report/sip.spec.tsx @@ -3,6 +3,8 @@ import { Element, h } from "@siteimprove/alfa-dom"; import { Response } from "@siteimprove/alfa-http"; import { Serializable } from "@siteimprove/alfa-json"; import { Map } from "@siteimprove/alfa-map"; +import { None, Option } from "@siteimprove/alfa-option"; +import { Err, Ok } from "@siteimprove/alfa-result"; import { Sequence } from "@siteimprove/alfa-sequence"; import { test } from "@siteimprove/alfa-test-deprecated"; import { URL } from "@siteimprove/alfa-url"; @@ -174,18 +176,34 @@ test("Metadata.payload() uses test name if provided", async (t) => { }); test("Metadata.payload() includes commit information if provided", async (t) => { - const actual = await Metadata.payload( - makeAudit(), - { commitInformation: { BranchName: "hello", Origin: "somewhere" } }, - timestamp - ); - - t.deepEqual( - actual, - makePayload({ - CommitInformation: { BranchName: "hello", Origin: "somewhere" }, - }) - ); + for (const commitInformation of [ + { BranchName: "hello", Origin: "somewhere" }, + Option.of({ BranchName: "hello", Origin: "somewhere" }), + Ok.of({ BranchName: "hello", Origin: "somewhere" }), + ]) { + const actual = await Metadata.payload( + makeAudit(), + { commitInformation }, + timestamp + ); + + t.deepEqual( + actual, + makePayload({ + CommitInformation: { BranchName: "hello", Origin: "somewhere" }, + }) + ); + } + + for (const commitInformation of [undefined, None, Err.of("invalid")]) { + const actual = await Metadata.payload( + makeAudit(), + { commitInformation }, + timestamp + ); + + t.deepEqual(actual, makePayload()); + } }); test("Metadata.payload() builds test name from commit information", async (t) => { @@ -403,7 +421,7 @@ test(".upload returns an error on missing API key", async (t) => { const actual = await SIP.upload(makeAudit({ page }), { userName: "foo@foo.com", - siteID: "12345" + siteID: "12345", }); t(actual.isErr()); diff --git a/yarn.lock b/yarn.lock index fb9f41c0..505e0fd7 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3048,6 +3048,7 @@ __metadata: "@siteimprove/alfa-refinement": "npm:^0.96.0" "@siteimprove/alfa-result": "npm:^0.96.0" "@siteimprove/alfa-rules": "npm:^0.96.0" + "@siteimprove/alfa-selective": "npm:^0.96.0" "@siteimprove/alfa-selector": "npm:^0.96.0" "@siteimprove/alfa-sequence": "npm:^0.96.0" "@siteimprove/alfa-test-deprecated": "npm:^0.96.0"