Accept optional siteID in Code Checker uploads (#106)

* Accept optional siteID in upload

* Don't include undefined siteID in payload

* Update documentation

.changeset/itchy-pens-return.md

@@ -0,0 +1,7 @@
+---
+"@siteimprove/alfa-test-utils": minor
+---
+
+**Added:** `SIP.upload` now accepts an optional `siteID` parameter.
+
+This should be the site ID of your site in the Siteimprove Intelligence Platform. It can be use to group tests by site and generate more accurate metadata and aggregates.

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

@@ -254,6 +254,7 @@ export namespace SIP {
                 CantTell: number;
                 Durations: RuleDurations;
             }>;
+            SiteId?: string;
             TestName?: string;
             Version: `${number}.${number}.${number}`;
         }
@@ -272,6 +273,7 @@ export namespace SIP {
         includeGitInfo?: boolean;
         pageTitle?: string | ((page: Page) => string);
         pageURL?: string | ((page: Page) => string);
+        siteID?: string;
         testName?: string | ((git: CommitInformation) => string);
         userName?: string;
     }

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

@@ -36,6 +36,22 @@ const pageReportURL = Audit.run(alfaPage, {
 });
 ```
 
+## Including the site ID
+
+If you are testing a page that belongs to a specific site in the Siteimprove Intelligence Platform, you can provide the site ID. This will help produce better metadata and aggregates.
+
+```typescript
+const pageReportURL = Audit.run(alfaPage, {
+  rules: { include: Rules.aaFilter },
+}).then((alfaResult) => {
+  SIP.upload(alfaResult, {
+    userName: process.env.SI_USER_NAME!,
+    apiKey: process.env.SI_API_KEY!,
+    siteId: "123456",
+  });
+});
+```
+
 ## Skipping git information
 
 If you prefer not to upload basic git information about the repository (origin URL; branch name; latest commit hash, author, and message), use the `includeGitInfo: false` option:
@@ -47,5 +63,3 @@ SIP.upload(alfaResult, {
   includeGitInfo: false,
 });
 ```
-
-

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

@@ -95,6 +95,11 @@ export namespace SIP {
      */
     apiKey?: string;
 
+    /**
+     * The site ID in the Siteimprove Intelligence Platform.
+     */
+    siteID?: string;
+
     /**
      * The URL of the page, or a function to build it from the audited page.
      * Defaults to the URL used to scrape the page.
@@ -150,11 +155,10 @@ export namespace SIP {
        */
       Version: `${number}.${number}.${number}`;
 
-      // Ignored for now.
-      // /**
-      //  * The site ID to which the page belongs in the Siteimprove Intelligence Platform.
-      //  */
-      // SiteId?: string;
+      /**
+       * The site ID to which the page belongs in the Siteimprove Intelligence Platform.
+       */
+      SiteId?: string;
 
       /**
        * Information about the latest git commit
@@ -272,6 +276,10 @@ export namespace SIP {
         result.CommitInformation = gitInfo.get();
       }
 
+      if (options.siteID !== undefined) {
+        result.SiteId = options.siteID;
+      }
+
       return result;
     }
 

packages/alfa-test-utils/test/report/sip.spec.tsx

@@ -162,6 +162,18 @@ test("S3.axiosConfig() creates an axios config", (t) => {
   });
 });
 
+test("Metadata.payload() uses site ID if provided", async (t) => {
+  const actual = await Metadata.payload(
+    makeAudit(),
+    { siteID: "12345" },
+    timestamp
+  );
+  t.notEqual(actual.CommitInformation, undefined);
+  delete actual.CommitInformation;
+
+  t.deepEqual(actual, makePayload({ SiteId: "12345" }));
+});
+
 test("Metadata.payload() uses test name if provided", async (t) => {
   const actual = await Metadata.payload(
     makeAudit(),