Alfa test utils (#59)

* Set up dummy package

* Add basic updload function

* Post-merge clean up

* Add wrapper to upload data to SIP

* Split API key and user name

* Post merge install

* Fix payload

* Add basic test

* Add outcome serialisation test

* Add more config tests

* Accept axios as external dependency

* Update documentation

* Add some upload mocked test

* Stabilise tests

* Update documentation

* Add missing dev dependencies

* Clean up

* Extract API

* Post-merge cleanup

* Use endpoint with pre-signed URLs

* Adapt config tests

* Adapt upload tests

* Update documentation

* Update documentation

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

.changeset/spotty-toes-sniff.md

@@ -0,0 +1,9 @@
+---
+"@siteimprove/alfa-test-utils": minor
+---
+
+**Added:** New packge for handling test utilities and interaction with Siteimprove Intelligence Platform.
+
+A new package is now available, intended to wrap several test utilities. It currently contains
+
+- a wrapper to upload audit results to the Siteimprove Intelligence Platform and see them in the Page Report

config/validate-structure.json

@@ -29,6 +29,7 @@
       "@siteimprove/alfa-puppeteer": ["puppeteer"],
       "@siteimprove/alfa-react": ["react", "react-test-renderer"],
       "@siteimprove/alfa-scraper": ["puppeteer"],
+      "@siteimprove/alfa-test-utils": ["axios"],
       "@siteimprove/alfa-unexpected": ["unexpected"],
       "@siteimprove/alfa-vue": [
         "@vue/test-utils",

docs/review/api/alfa-test-utils.api.md

@@ -0,0 +1,78 @@
+## API Report File for "@siteimprove/alfa-test-utils"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { AxiosRequestConfig } from 'axios';
+import type { Flattened } from '@siteimprove/alfa-rules';
+import { Outcome } from '@siteimprove/alfa-act';
+import { Page } from '@siteimprove/alfa-web';
+
+// @public
+export type alfaOutcome = Outcome<Flattened.Input, Flattened.Target, Flattened.Question, Flattened.Subject>;
+
+// @public
+export namespace SIP {
+    // @internal (undocumented)
+    export namespace Defaults {
+        const // (undocumented)
+        URL = "https://api.siteimprove.com/v2/a11y/AlfaDevCheck/CreateReport";
+        const // (undocumented)
+        Title = "Unnamed page";
+        const // (undocumented)
+        Name = "Accessibility Code Checker";
+    }
+    // @internal
+    export namespace Metadata {
+        export function axiosConfig(page: Page, options: Options, override: {
+            url?: string;
+            timestamp?: number;
+        }, defaultTitle?: string, defaultName?: string): AxiosRequestConfig;
+        export function params(url: string, apiKey: string): AxiosRequestConfig;
+        // (undocumented)
+        export interface Payload {
+            // (undocumented)
+            PageTitle: string;
+            // (undocumented)
+            RequestTimeStampMilliseconds: number;
+            // (undocumented)
+            TestName: string;
+            // (undocumented)
+            Version: `${number}.${number}.${number}`;
+        }
+        export function payload(PageTitle: string, TestName: string, timestamp: number): Payload;
+            {};
+    }
+    // (undocumented)
+    export interface Options {
+        apiKey: string;
+        pageTitle?: string;
+        testName?: string;
+        userName: string;
+    }
+    // @internal
+    export namespace S3 {
+        export function axiosConfig(id: string, url: string, page: Page, outcomes: Iterable<alfaOutcome>): AxiosRequestConfig;
+        export function params(url: string): AxiosRequestConfig;
+        // (undocumented)
+        export interface Payload {
+            // (undocumented)
+            Aspects: string;
+            // (undocumented)
+            CheckResult: string;
+            // (undocumented)
+            Id: string;
+        }
+        export function payload(Id: string, page: Page, outcomes: Iterable<alfaOutcome>): Payload;
+            {};
+    }
+    export function upload(page: Page, outcomes: Iterable<alfaOutcome>, options: Options): Promise<string>;
+    // @internal
+    export function upload(page: Page, outcomes: Iterable<alfaOutcome>, options: Options, override: {
+        url?: string;
+        timestamp?: number;
+    }): Promise<string>;
+}
+
+```

packages/alfa-test-utils/config/api-extractor.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../../config/api-extractor.json",
+  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts"
+}

packages/alfa-test-utils/package.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json.schemastore.org/package",
+  "name": "@siteimprove/alfa-test-utils",
+  "homepage": "https://alfa.siteimprove.com",
+  "version": "0.68.4",
+  "license": "MIT",
+  "description": "Utilities to run Alfa tests and upload results to the Siteimprove Intelligence Platform",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siteimprove/alfa-integrations.git",
+    "directory": "packages/alfa-test-utils"
+  },
+  "bugs": "https://github.com/siteimprove/alfa/issues",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://npm.pkg.github.com/"
+  },
+  "dependencies": {
+    "@siteimprove/alfa-act": "^0.88.0",
+    "@siteimprove/alfa-dom": "^0.88.0",
+    "@siteimprove/alfa-json": "^0.88.0",
+    "@siteimprove/alfa-rules": "^0.88.0",
+    "@siteimprove/alfa-sequence": "^0.88.0",
+    "@siteimprove/alfa-web": "^0.88.0",
+    "axios": "^1.7.2"
+  },
+  "devDependencies": {
+    "@siteimprove/alfa-device": "^0.88.0",
+    "@siteimprove/alfa-http": "^0.88.0",
+    "@siteimprove/alfa-result": "^0.88.0",
+    "@siteimprove/alfa-test": "^0.88.0",
+    "axios-mock-adapter": "^1.22.0"
+  }
+}

packages/alfa-test-utils/src/common.ts

@@ -0,0 +1,14 @@
+import { Outcome } from "@siteimprove/alfa-act";
+import type { Flattened as Rule } from "@siteimprove/alfa-rules";
+
+/**
+ * The type of individual outcomes produced by Alfa rules.
+ *
+ * @public
+ */
+export type alfaOutcome = Outcome<
+  Rule.Input,
+  Rule.Target,
+  Rule.Question,
+  Rule.Subject
+>;

packages/alfa-test-utils/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * A library for running Alfa tests and uploading results to the Siteimprove
+ * Intelligence Platform.
+ *
+ * @packageDocumentation
+ */
+export * from "./common.js";
+export * from "./report/index.js";

packages/alfa-test-utils/src/report/index.ts

@@ -0,0 +1 @@
+export * from "./sip.js"