test(a11y): capture android qa hierarchy evidence

Author: iexitdev

docs/release/accessibility-qa.md

@@ -51,10 +51,23 @@ npm run release:qa:capture -- \
   --matrix accessibility \
   --row ios-voiceover-line-charts \
   --platform ios \
-  --output docs/release/artifacts/ios-voiceover-line-charts.png
+  --output docs/release/artifacts/ios-voiceover-line-charts.png \
+  --ios-log-output docs/release/artifacts/ios-voiceover-line-charts.log
 ```
 
-Use `--device <simulator-udid-or-adb-serial>` for a specific target and `--no-launch` when the screen-reader state is already positioned on the target page. Record the artifact with `npm run release:qa:record -- --matrix accessibility --row <row-id> --status pass --evidence <artifact> --reviewed-by <name> --device "<device/os>" --build-surface "<build>" --notes "<screen-reader checks passed>"` only after the required VoiceOver or TalkBack checks pass.
+Android TalkBack rows can also capture a UIAutomator hierarchy snapshot:
+
+```sh
+npm run release:qa:capture -- \
+  --matrix accessibility \
+  --row android-talkback-line-charts \
+  --platform android \
+  --output docs/release/artifacts/android-talkback-line-charts.png \
+  --android-log-output docs/release/artifacts/android-talkback-line-charts.log \
+  --android-ui-output docs/release/artifacts/android-talkback-line-charts.xml
+```
+
+Use `--device <simulator-udid-or-adb-serial>` for a specific target and `--no-launch` when the screen-reader state is already positioned on the target page. The iOS log and Android UI hierarchy artifacts are supporting evidence; they do not replace the required VoiceOver or TalkBack manual review. Record the artifacts with `npm run release:qa:record -- --matrix accessibility --row <row-id> --status pass --evidence <artifact> --evidence <log-or-ui-artifact> --reviewed-by <name> --device "<device/os>" --build-surface "<build>" --notes "<screen-reader checks passed>"` only after the required VoiceOver or TalkBack checks pass.
 
 Representative stories on the Line, Bar, Combined, Financial, Pie & Donut, Progress, and Heatmaps pages include a collapsed `Data details` panel. Use those panels during VoiceOver and TalkBack review to verify the table-fallback checks without making the public preview visually dense by default.
 

scripts/capture-native-qa-options.mjs

@@ -8,6 +8,7 @@ export const captureNativeQaUsage = `Usage:
 Options:
   --android-log-output <path>  Also clear/capture Android logcat to this repo-relative path.
   --android-log-lines <number> Number of trailing logcat lines to capture. Defaults to 400.
+  --android-ui-output <path>   Also capture Android UIAutomator hierarchy XML.
   --device <id>             iOS simulator UDID or Android adb serial. Defaults to booted/default device.
   --dry-run                 Print launch and screenshot commands without executing them.
   --ios-log-output <path>    Also capture iOS simulator logs to this repo-relative path.
@@ -47,6 +48,8 @@ export const parseCaptureNativeQaArgs = (argv) => {
       options.androidLogLines = Number(readValue());
     } else if (arg === "--android-log-output") {
       options.androidLogOutput = readValue();
+    } else if (arg === "--android-ui-output") {
+      options.androidUiOutput = readValue();
     } else if (arg === "--device") {
       options.device = readValue();
     } else if (arg === "--dry-run") {

scripts/capture-native-qa-screenshot.mjs

@@ -43,6 +43,7 @@ const shouldWaitAfterCommand = ({ args, command }) =>
 const validateCaptureOptions = ({
   androidLogLines,
   androidLogOutput,
+  androidUiOutput,
   iosLogLast,
   iosLogOutput,
   iosLogPredicate,
@@ -56,6 +57,10 @@ const validateCaptureOptions = ({
     throw new Error("--android-log-output can only be used with Android");
   }
 
+  if (androidUiOutput && platform !== "android") {
+    throw new Error("--android-ui-output can only be used with Android");
+  }
+
   if (iosLogOutput && platform !== "ios") {
     throw new Error("--ios-log-output can only be used with iOS");
   }
@@ -170,11 +175,13 @@ const buildAndroidCommands = ({
   androidLogLines,
   androidLogOutputPath,
   androidPackage,
+  androidUiOutputPath,
   device,
   launch,
   launchUrl
 }) => {
   const commands = [];
+  const uiDumpPath = "/sdcard/chartkit-native-qa-window.xml";
 
   if (androidLogOutputPath) {
     commands.push({
@@ -196,6 +203,26 @@ const buildAndroidCommands = ({
     writesStdoutToFile: true
   });
 
+  if (androidUiOutputPath) {
+    commands.push({
+      args: [
+        ...(device ? ["-s", device] : []),
+        "shell",
+        "uiautomator",
+        "dump",
+        uiDumpPath
+      ],
+      command: "adb"
+    });
+    commands.push({
+      args: [...(device ? ["-s", device] : []), "exec-out", "cat", uiDumpPath],
+      command: "adb",
+      encoding: "utf8",
+      outputPath: androidUiOutputPath,
+      writesStdoutToFile: true
+    });
+  }
+
   if (androidLogOutputPath) {
     commands.push({
       args: [
@@ -240,6 +267,7 @@ export const createNativeQaScreenshotPlan = async ({
   androidLogLines = 400,
   androidLogOutput,
   androidPackage = defaultAndroidPackage,
+  androidUiOutput,
   device,
   iosLogLast = "2m",
   iosLogOutput,
@@ -255,6 +283,7 @@ export const createNativeQaScreenshotPlan = async ({
   validateCaptureOptions({
     androidLogLines,
     androidLogOutput,
+    androidUiOutput,
     iosLogLast,
     iosLogOutput,
     iosLogPredicate,
@@ -267,13 +296,17 @@ export const createNativeQaScreenshotPlan = async ({
   const absoluteAndroidLogOutputPath = androidLogOutput
     ? path.resolve(repoRoot, androidLogOutput)
     : undefined;
+  const absoluteAndroidUiOutputPath = androidUiOutput
+    ? path.resolve(repoRoot, androidUiOutput)
+    : undefined;
   const absoluteIosLogOutputPath = iosLogOutput
     ? path.resolve(repoRoot, iosLogOutput)
     : undefined;
   const commandOptions = {
     androidLogLines,
     androidLogOutputPath: absoluteAndroidLogOutputPath,
     androidPackage,
+    androidUiOutputPath: absoluteAndroidUiOutputPath,
     device,
     iosLogLast,
     iosLogOutputPath: absoluteIosLogOutputPath,
@@ -289,9 +322,11 @@ export const createNativeQaScreenshotPlan = async ({
 
   return {
     absoluteAndroidLogOutputPath,
+    absoluteAndroidUiOutputPath,
     absoluteIosLogOutputPath,
     absoluteOutputPath,
     androidLogOutput,
+    androidUiOutput,
     commands,
     iosLogOutput,
     launchUrl: row.launchUrl,
@@ -301,6 +336,7 @@ export const createNativeQaScreenshotPlan = async ({
       "--status partial",
       `--evidence ${outputPath}`,
       androidLogOutput ? `--evidence ${androidLogOutput}` : "",
+      androidUiOutput ? `--evidence ${androidUiOutput}` : "",
       iosLogOutput ? `--evidence ${iosLogOutput}` : ""
     ]
       .filter(Boolean)
@@ -327,6 +363,11 @@ export const captureNativeQaScreenshot = async ({
       recursive: true
     });
   }
+  if (plan.absoluteAndroidUiOutputPath) {
+    await mkdir(path.dirname(plan.absoluteAndroidUiOutputPath), {
+      recursive: true
+    });
+  }
   if (plan.absoluteIosLogOutputPath) {
     await mkdir(path.dirname(plan.absoluteIosLogOutputPath), {
       recursive: true

scripts/capture-native-qa-screenshot.test.mjs

@@ -241,6 +241,68 @@ describe("native QA screenshot capture", () => {
     expect(logcat).toBe("logcat lines");
   });
 
+  it("can capture Android UI hierarchy evidence with the screenshot", async () => {
+    const tempRepo = await createTempRepo();
+    const calls = [];
+    const result = await captureNativeQaScreenshot({
+      androidUiOutput: "docs/release/artifacts/android-line-ui.xml",
+      matrixName: "runtime",
+      output: "docs/release/artifacts/android-line.png",
+      platform: "android",
+      repoRoot: tempRepo,
+      rowId: "android-line-charts",
+      runner: (command) => {
+        calls.push(command);
+
+        return command.encoding === "buffer"
+          ? Buffer.from("png-bytes")
+          : "<hierarchy />";
+      },
+      waitMs: 0
+    });
+    const uiHierarchy = await readFile(
+      join(tempRepo, "docs/release/artifacts/android-line-ui.xml"),
+      "utf8"
+    );
+
+    expect(result.recordCommand).toBe(
+      "npm run release:qa:record -- --matrix runtime --row android-line-charts --status partial --evidence docs/release/artifacts/android-line.png --evidence docs/release/artifacts/android-line-ui.xml"
+    );
+    expect(calls.map((call) => call.args)).toEqual([
+      [
+        "shell",
+        "am",
+        "start",
+        "-W",
+        "-a",
+        "android.intent.action.VIEW",
+        "-d",
+        "'chartkitshowcase://showcase?view=charts&page=line-area'",
+        "io.chartkit.showcase"
+      ],
+      ["exec-out", "screencap", "-p"],
+      ["shell", "uiautomator", "dump", "/sdcard/chartkit-native-qa-window.xml"],
+      ["exec-out", "cat", "/sdcard/chartkit-native-qa-window.xml"]
+    ]);
+    expect(uiHierarchy).toBe("<hierarchy />");
+  });
+
+  it("can combine Android screenshot, UI hierarchy, and logcat evidence", async () => {
+    const plan = await createNativeQaScreenshotPlan({
+      androidLogOutput: "docs/release/artifacts/android-line.log",
+      androidUiOutput: "docs/release/artifacts/android-line-ui.xml",
+      matrixName: "runtime",
+      output: "docs/release/artifacts/android-line.png",
+      platform: "android",
+      repoRoot,
+      rowId: "android-line-charts"
+    });
+
+    expect(plan.recordCommand).toBe(
+      "npm run release:qa:record -- --matrix runtime --row android-line-charts --status partial --evidence docs/release/artifacts/android-line.png --evidence docs/release/artifacts/android-line.log --evidence docs/release/artifacts/android-line-ui.xml"
+    );
+  });
+
   it("can skip launching and capture the current Android screen", async () => {
     const plan = await createNativeQaScreenshotPlan({
       launch: false,
@@ -295,4 +357,17 @@ describe("native QA screenshot capture", () => {
       })
     ).rejects.toThrow("--ios-log-output can only be used with iOS");
   });
+
+  it("rejects Android UI output for iOS captures", async () => {
+    await expect(
+      captureNativeQaScreenshot({
+        androidUiOutput: "docs/release/artifacts/ios-line.xml",
+        dryRun: true,
+        matrixName: "runtime",
+        platform: "ios",
+        repoRoot,
+        rowId: "ios-line-charts"
+      })
+    ).rejects.toThrow("--android-ui-output can only be used with Android");
+  });
 });