Test utils improvements (#114)

* Accept various form of optional commit information
* Update documentation

.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`.

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<CommitInformation> | Result<CommitInformation, unknown>;
         pageTitle?: string | ((page: Page) => string);
         pageURL?: string | ((page: Page) => string);
         siteID?: string;

packages/alfa-test-utils/docs/usage/reporting/advanced.md

@@ -2,18 +2,22 @@
 
 ## 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) => {
   SIP.upload(alfaResult, {
     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}`,
   });
 });
 ```

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",

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<CommitInformation>
+      | Result<CommitInformation, unknown>;
   }
 
   /**
@@ -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<CommitInformation>, (info) => info)
+        .if(Result.isResult<CommitInformation, unknown>, (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

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());

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"