@fluentui-react-native/desktop-driver 0.2.0

package/src/artifacts/ArtifactManager.ts

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { DesktopArtifact, DesktopStoryRunResult } from '../authoring/results.js';
+
+export class ArtifactManager {
+  readonly root: string;
+
+  constructor(root: string) {
+    if (!root) {
+      throw new TypeError('ArtifactManager requires a non-empty root path.');
+    }
+    fs.mkdirSync(root, { recursive: true });
+    this.root = fs.realpathSync.native(root);
+  }
+
+  writeScreenshot(testDirectory: string, name: string, base64: string): DesktopArtifact {
+    return this.write(testDirectory, name, 'png', Buffer.from(base64, 'base64'), 'screenshot');
+  }
+
+  writeSource(testDirectory: string, name: string, source: string): DesktopArtifact {
+    return this.write(testDirectory, name, 'xml', source, 'source');
+  }
+
+  writeTree(testDirectory: string, name: string, tree: unknown): DesktopArtifact {
+    return this.write(testDirectory, name, 'json', `${JSON.stringify(tree, null, 2)}\n`, 'tree');
+  }
+
+  writeRunResult(result: DesktopStoryRunResult): string {
+    const outputPath = this.resolvePath('run.json');
+    writeAtomic(outputPath, `${JSON.stringify(result, null, 2)}\n`);
+    return outputPath;
+  }
+
+  writeMetadata(name: string, value: unknown): string {
+    const outputPath = this.resolvePath(`${sanitizeSegment(name)}.json`);
+    writeAtomic(outputPath, `${JSON.stringify(value, null, 2)}\n`);
+    return outputPath;
+  }
+
+  private write(
+    testDirectory: string,
+    name: string,
+    extension: string,
+    data: string | Uint8Array,
+    kind: DesktopArtifact['kind'],
+  ): DesktopArtifact {
+    const safeDirectory = sanitizeSegment(testDirectory);
+    const safeName = sanitizeSegment(name);
+    const relativePath = path.join('tests', safeDirectory, `${safeName}.${extension}`);
+    const outputPath = this.resolvePath(relativePath);
+    writeAtomic(outputPath, data);
+    return {
+      kind,
+      name,
+      path: relativePath.split(path.sep).join('/'),
+    };
+  }
+
+  private resolvePath(relativePath: string): string {
+    if (path.isAbsolute(relativePath)) {
+      throw new Error('Artifact paths must be relative to the configured root.');
+    }
+    const outputPath = path.resolve(this.root, relativePath);
+    const relative = path.relative(this.root, outputPath);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new Error(`Artifact path escapes the configured root: ${relativePath}`);
+    }
+    const parent = path.dirname(outputPath);
+    fs.mkdirSync(parent, { recursive: true });
+    const realParent = fs.realpathSync.native(parent);
+    const realRelative = path.relative(this.root, realParent);
+    if (realRelative === '..' || realRelative.startsWith(`..${path.sep}`) || path.isAbsolute(realRelative)) {
+      throw new Error(`Artifact path traverses outside the configured root: ${relativePath}`);
+    }
+    return path.join(realParent, path.basename(outputPath));
+  }
+}
+
+function sanitizeSegment(value: string): string {
+  let sanitized = value
+    .replaceAll(/[^A-Za-z0-9._-]/g, '-')
+    .replaceAll(/-+/g, '-')
+    .replace(/^\.+/, '');
+  if (/^(?:aux|con|nul|prn|com[1-9]|lpt[1-9])(?:\.|$)/i.test(sanitized)) {
+    sanitized = `_${sanitized}`;
+  }
+  if (!sanitized || sanitized === '.' || sanitized === '..') {
+    throw new Error(`Invalid artifact name "${value}".`);
+  }
+  return sanitized;
+}
+
+function writeAtomic(outputPath: string, data: string | Uint8Array): void {
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const temporaryPath = `${outputPath}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporaryPath, data);
+    fs.renameSync(temporaryPath, outputPath);
+  } catch (error) {
+    fs.rmSync(temporaryPath, { force: true });
+    throw error;
+  }
+}

package/src/artifacts/index.ts

@@ -0,0 +1 @@
+export { ArtifactManager } from './ArtifactManager.js';

package/src/authoring/index.ts

@@ -0,0 +1,26 @@
+export type {
+  DesktopArtifact,
+  DesktopRunStatus,
+  DesktopStepStatus,
+  DesktopStoryRunResult,
+  DesktopStoryStepResult,
+  DesktopStoryTestResult,
+  DesktopTestStatus,
+} from './results.js';
+export {
+  defineDesktopStoryTests,
+  desktopBy,
+  desktopStoryCapabilities,
+  desktopStoryPlatforms,
+  validateDesktopStoryTests,
+} from './storyTests.js';
+export type {
+  DesktopStoryCapability,
+  DesktopStoryExpectation,
+  DesktopStoryPlatform,
+  DesktopStorySelector,
+  DesktopStoryState,
+  DesktopStoryStep,
+  DesktopStoryTest,
+  DesktopStoryTests,
+} from './storyTests.js';

package/src/authoring/results.ts

@@ -0,0 +1,47 @@
+import type { DesktopEndpoint, DesktopPlatformName } from '../protocol/types.js';
+
+export type DesktopArtifact = {
+  kind: 'screenshot' | 'source' | 'tree';
+  name: string;
+  path: string;
+};
+
+export type DesktopStepStatus = 'failed' | 'passed' | 'skipped';
+export type DesktopTestStatus = 'cancelled' | 'failed' | 'infrastructure-error' | 'passed' | 'skipped' | 'timed-out';
+export type DesktopRunStatus = 'failed' | 'passed';
+
+export type DesktopStoryStepResult = {
+  artifacts: readonly DesktopArtifact[];
+  durationMs: number;
+  error?: string;
+  index: number;
+  status: DesktopStepStatus;
+};
+
+export type DesktopStoryTestResult = {
+  artifacts: readonly DesktopArtifact[];
+  durationMs: number;
+  error?: string;
+  skipReason?: string;
+  status: DesktopTestStatus;
+  steps: readonly DesktopStoryStepResult[];
+  storyId: string;
+  testId: string;
+  title: string;
+};
+
+export type DesktopStoryRunResult = {
+  endpoint: DesktopEndpoint;
+  finishedAt: string;
+  manifest: {
+    platform: string;
+    portable: string;
+  };
+  platformName: DesktopPlatformName;
+  runId: string;
+  schemaVersion: 1;
+  startedAt: string;
+  status: DesktopRunStatus;
+  targetId: string;
+  tests: readonly DesktopStoryTestResult[];
+};

package/src/authoring/storyTests.test.ts

@@ -0,0 +1,58 @@
+import { validateDesktopStoryTests } from './storyTests.js';
+
+describe('validateDesktopStoryTests', () => {
+  test('accepts a serializable versioned plan', () => {
+    const plan = {
+      version: 1,
+      tests: [{ id: 'click', steps: [{ action: 'click', target: { testId: 'button' } }] }],
+    } as const;
+
+    expect(validateDesktopStoryTests(plan)).toBe(plan);
+  });
+
+  test('rejects duplicate ids and executable values', () => {
+    expect(() =>
+      validateDesktopStoryTests({
+        version: 1,
+        tests: [
+          { id: 'duplicate', steps: [{ action: 'note', message: 'first' }] },
+          { id: 'duplicate', steps: [{ action: 'note', message: 'second' }] },
+        ],
+      }),
+    ).toThrow('duplicate test id');
+    expect(() =>
+      validateDesktopStoryTests({
+        version: 1,
+        tests: [{ id: 'function', steps: [{ action: 'setArgs', args: { run: () => undefined } }] }],
+      }),
+    ).toThrow('JSON-serializable');
+  });
+
+  test('rejects non-finite numbers before digest serialization', () => {
+    expect(() =>
+      validateDesktopStoryTests({
+        version: 1,
+        tests: [
+          {
+            id: 'non-finite',
+            steps: [{ action: 'setArgs', args: { invalid: Number.POSITIVE_INFINITY } }],
+          },
+        ],
+      }),
+    ).toThrow('finite numbers');
+  });
+
+  test('rejects malformed authored W3C action sequences', () => {
+    expect(() =>
+      validateDesktopStoryTests({
+        version: 1,
+        tests: [
+          {
+            id: 'invalid-actions',
+            steps: [{ action: 'actions', sequences: [{ id: 'bad', type: 'key', actions: [{ type: 'pointerDown' }] }] }],
+          },
+        ],
+      }),
+    ).toThrow('sequences are invalid');
+  });
+});

package/src/authoring/storyTests.ts

@@ -0,0 +1,345 @@
+import type { WebDriverActionSequence } from '../protocol/types.js';
+import { createInputState, parseActionSequences } from '../protocol/actions.js';
+
+export const desktopStoryPlatforms = ['macos', 'windows', 'win32'] as const;
+export const desktopStoryCapabilities = [
+  'accessibility-click',
+  'element-screenshot',
+  'focus',
+  'keyboard',
+  'physical-click',
+  'screenshot',
+  'wheel',
+] as const;
+
+export type DesktopStoryPlatform = (typeof desktopStoryPlatforms)[number];
+export type DesktopStoryCapability = (typeof desktopStoryCapabilities)[number];
+
+export type DesktopStorySelector = { testId: string } | { role: string; name?: string } | { accessibleName: string } | { text: string };
+
+export type DesktopStoryState =
+  | 'accessibleName'
+  | 'checked'
+  | 'count'
+  | 'displayed'
+  | 'enabled'
+  | 'expanded'
+  | 'exists'
+  | 'focused'
+  | 'role'
+  | 'selected'
+  | 'text'
+  | 'value';
+
+export type DesktopStoryExpectation = {
+  state: DesktopStoryState;
+  target: DesktopStorySelector;
+  value?: boolean | number | string;
+};
+
+export type DesktopStoryStep =
+  | { action: 'actions'; sequences: readonly WebDriverActionSequence[] }
+  | { action: 'clear' | 'click' | 'doubleClick'; target: DesktopStorySelector }
+  | { action: 'keys'; value: readonly string[] }
+  | { action: 'note'; message: string }
+  | { action: 'screenshot'; name: string; target?: DesktopStorySelector }
+  | { action: 'scroll'; deltaX?: number; deltaY: number; target?: DesktopStorySelector }
+  | { action: 'setArgs'; args: Readonly<Record<string, unknown>> }
+  | { action: 'source'; name: string }
+  | { action: 'type'; target: DesktopStorySelector; text: string }
+  | { action: 'wait'; target?: DesktopStorySelector; timeoutMs?: number; until?: DesktopStoryExpectation }
+  | { expect: DesktopStoryExpectation };
+
+export type DesktopStoryTest = {
+  id: string;
+  platforms?: readonly DesktopStoryPlatform[];
+  requires?: readonly DesktopStoryCapability[];
+  steps: readonly DesktopStoryStep[];
+  title?: string;
+};
+
+export type DesktopStoryTests = {
+  portable?: boolean;
+  tests: readonly DesktopStoryTest[];
+  version: 1;
+};
+
+export const desktopBy = {
+  accessibleName: (accessibleName: string): DesktopStorySelector => ({ accessibleName }),
+  role: (role: string, name?: string): DesktopStorySelector => ({ role, ...(name ? { name } : {}) }),
+  testId: (testId: string): DesktopStorySelector => ({ testId }),
+  text: (text: string): DesktopStorySelector => ({ text }),
+};
+
+export function defineDesktopStoryTests(plan: DesktopStoryTests): DesktopStoryTests {
+  return validateDesktopStoryTests(plan);
+}
+
+export function validateDesktopStoryTests(value: unknown, source = 'desktopDriver'): DesktopStoryTests {
+  const plan = requireObject(value, source);
+  requireExactKeys(plan, ['portable', 'tests', 'version'], source);
+  if (plan.version !== 1) {
+    throw new TypeError(`${source}.version must be 1.`);
+  }
+  if (plan.portable !== undefined && typeof plan.portable !== 'boolean') {
+    throw new TypeError(`${source}.portable must be a boolean when provided.`);
+  }
+  if (!Array.isArray(plan.tests)) {
+    throw new TypeError(`${source}.tests must be an array.`);
+  }
+
+  const ids = new Set<string>();
+  for (const [index, value] of plan.tests.entries()) {
+    validateTest(value, `${source}.tests[${index}]`, ids);
+  }
+  assertJsonValue(value, source);
+  return value as DesktopStoryTests;
+}
+
+function validateTest(value: unknown, source: string, ids: Set<string>): void {
+  const test = requireObject(value, source);
+  requireExactKeys(test, ['id', 'platforms', 'requires', 'steps', 'title'], source);
+  if (typeof test.id !== 'string' || !test.id) {
+    throw new TypeError(`${source}.id must be a non-empty string.`);
+  }
+  if (ids.has(test.id)) {
+    throw new TypeError(`${source} contains duplicate test id "${test.id}".`);
+  }
+  ids.add(test.id);
+  if (test.title !== undefined && (typeof test.title !== 'string' || !test.title)) {
+    throw new TypeError(`${source}.title must be a non-empty string when provided.`);
+  }
+  validateEnumArray(test.platforms, desktopStoryPlatforms, `${source}.platforms`);
+  validateEnumArray(test.requires, desktopStoryCapabilities, `${source}.requires`);
+  if (!Array.isArray(test.steps) || test.steps.length === 0) {
+    throw new TypeError(`${source}.steps must be a non-empty array.`);
+  }
+  for (const [index, step] of test.steps.entries()) {
+    validateStep(step, `${source}.steps[${index}]`);
+  }
+}
+
+function validateStep(value: unknown, source: string): void {
+  const step = requireObject(value, source);
+  if ('expect' in step) {
+    requireExactKeys(step, ['expect'], source);
+    validateExpectation(step.expect, `${source}.expect`);
+    return;
+  }
+  if (typeof step.action !== 'string') {
+    throw new TypeError(`${source}.action must be a supported action string.`);
+  }
+  switch (step.action) {
+    case 'actions':
+      requireExactKeys(step, ['action', 'sequences'], source);
+      if (!Array.isArray(step.sequences) || step.sequences.length === 0) {
+        throw new TypeError(`${source}.sequences must be a non-empty array.`);
+      }
+      try {
+        parseActionSequences(step.sequences, createInputState());
+      } catch (error) {
+        throw new TypeError(`${source}.sequences are invalid: ${(error as Error).message}`, { cause: error });
+      }
+      return;
+    case 'clear':
+    case 'click':
+    case 'doubleClick':
+      requireExactKeys(step, ['action', 'target'], source);
+      validateSelector(step.target, `${source}.target`);
+      return;
+    case 'keys':
+      requireExactKeys(step, ['action', 'value'], source);
+      if (!Array.isArray(step.value) || !step.value.every((key) => typeof key === 'string' && key.length > 0)) {
+        throw new TypeError(`${source}.value must be a non-empty string array.`);
+      }
+      return;
+    case 'note':
+      requireExactKeys(step, ['action', 'message'], source);
+      requireNonEmptyString(step.message, `${source}.message`);
+      return;
+    case 'screenshot':
+      requireExactKeys(step, ['action', 'name', 'target'], source);
+      requireNonEmptyString(step.name, `${source}.name`);
+      if (step.target !== undefined) {
+        validateSelector(step.target, `${source}.target`);
+      }
+      return;
+    case 'scroll':
+      requireExactKeys(step, ['action', 'deltaX', 'deltaY', 'target'], source);
+      requireFiniteNumber(step.deltaY, `${source}.deltaY`);
+      if (step.deltaX !== undefined) {
+        requireFiniteNumber(step.deltaX, `${source}.deltaX`);
+      }
+      if (step.target !== undefined) {
+        validateSelector(step.target, `${source}.target`);
+      }
+      return;
+    case 'setArgs':
+      requireExactKeys(step, ['action', 'args'], source);
+      requireObject(step.args, `${source}.args`);
+      return;
+    case 'source':
+      requireExactKeys(step, ['action', 'name'], source);
+      requireNonEmptyString(step.name, `${source}.name`);
+      return;
+    case 'type':
+      requireExactKeys(step, ['action', 'target', 'text'], source);
+      validateSelector(step.target, `${source}.target`);
+      if (typeof step.text !== 'string') {
+        throw new TypeError(`${source}.text must be a string.`);
+      }
+      return;
+    case 'wait':
+      requireExactKeys(step, ['action', 'target', 'timeoutMs', 'until'], source);
+      if (step.target !== undefined) {
+        validateSelector(step.target, `${source}.target`);
+      }
+      if (step.until !== undefined) {
+        validateExpectation(step.until, `${source}.until`);
+      }
+      if (step.target === undefined && step.until === undefined) {
+        throw new TypeError(`${source} requires "target" or "until".`);
+      }
+      if (step.timeoutMs !== undefined && (!Number.isInteger(step.timeoutMs) || (step.timeoutMs as number) < 0)) {
+        throw new TypeError(`${source}.timeoutMs must be a non-negative integer.`);
+      }
+      return;
+    default:
+      throw new TypeError(`${source}.action "${step.action}" is not supported.`);
+  }
+}
+
+function validateExpectation(value: unknown, source: string): void {
+  const expectation = requireObject(value, source);
+  requireExactKeys(expectation, ['state', 'target', 'value'], source);
+  if (
+    typeof expectation.state !== 'string' ||
+    !(
+      [
+        'accessibleName',
+        'checked',
+        'count',
+        'displayed',
+        'enabled',
+        'expanded',
+        'exists',
+        'focused',
+        'role',
+        'selected',
+        'text',
+        'value',
+      ] as const
+    ).includes(expectation.state as DesktopStoryState)
+  ) {
+    throw new TypeError(`${source}.state is not supported.`);
+  }
+  validateSelector(expectation.target, `${source}.target`);
+  if (expectation.value !== undefined && !['boolean', 'number', 'string'].includes(typeof expectation.value)) {
+    throw new TypeError(`${source}.value must be a boolean, number, or string.`);
+  }
+  if (typeof expectation.value === 'number' && !Number.isFinite(expectation.value)) {
+    throw new TypeError(`${source}.value must be finite.`);
+  }
+  if (expectation.state === 'count' && typeof expectation.value !== 'number') {
+    throw new TypeError(`${source}.value must be a number for a count assertion.`);
+  }
+  if (
+    (expectation.state === 'accessibleName' ||
+      expectation.state === 'role' ||
+      expectation.state === 'text' ||
+      expectation.state === 'value') &&
+    typeof expectation.value !== 'string'
+  ) {
+    throw new TypeError(`${source}.value must be a string for a ${expectation.state} assertion.`);
+  }
+  if (
+    (expectation.state === 'checked' ||
+      expectation.state === 'displayed' ||
+      expectation.state === 'enabled' ||
+      expectation.state === 'expanded' ||
+      expectation.state === 'exists' ||
+      expectation.state === 'focused' ||
+      expectation.state === 'selected') &&
+    expectation.value !== undefined &&
+    typeof expectation.value !== 'boolean' &&
+    !(expectation.state === 'checked' && expectation.value === 'mixed')
+  ) {
+    throw new TypeError(`${source}.value must be a boolean for a ${expectation.state} assertion.`);
+  }
+}
+
+function validateSelector(value: unknown, source: string): void {
+  const selector = requireObject(value, source);
+  const selectorKeys = ['accessibleName', 'role', 'testId', 'text'].filter((key) => selector[key] !== undefined);
+  if (selectorKeys.length !== 1) {
+    throw new TypeError(`${source} must define exactly one selector strategy.`);
+  }
+  const strategy = selectorKeys[0];
+  requireNonEmptyString(selector[strategy], `${source}.${strategy}`);
+  if (strategy === 'role') {
+    requireExactKeys(selector, ['name', 'role'], source);
+    if (selector.name !== undefined) {
+      requireNonEmptyString(selector.name, `${source}.name`);
+    }
+  } else {
+    requireExactKeys(selector, [strategy], source);
+  }
+}
+
+function validateEnumArray<T extends string>(value: unknown, allowed: readonly T[], source: string): void {
+  if (value === undefined) {
+    return;
+  }
+  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && allowed.includes(item as T))) {
+    throw new TypeError(`${source} contains an unsupported value.`);
+  }
+}
+
+function requireExactKeys(value: Record<string, unknown>, allowed: readonly string[], source: string): void {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new TypeError(`${source} contains unknown field "${unknown[0]}".`);
+  }
+}
+
+function requireNonEmptyString(value: unknown, source: string): asserts value is string {
+  if (typeof value !== 'string' || !value) {
+    throw new TypeError(`${source} must be a non-empty string.`);
+  }
+}
+
+function requireFiniteNumber(value: unknown, source: string): asserts value is number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new TypeError(`${source} must be a finite number.`);
+  }
+}
+
+function requireObject(value: unknown, source: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${source} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function assertJsonValue(value: unknown, source: string): void {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`${source} must contain only finite numbers.`);
+    }
+    return;
+  }
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertJsonValue(item, `${source}[${index}]`));
+    return;
+  }
+  if (typeof value === 'object') {
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      assertJsonValue(item, `${source}.${key}`);
+    }
+    return;
+  }
+  throw new TypeError(`${source} must contain only JSON-serializable values.`);
+}