@fluentui-react-native/desktop-driver 0.2.0

package/src/cli/DesktopDriverCli.test.ts

@@ -0,0 +1,150 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { createServer } from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { DesktopStoryManifest } from '../storybook.js';
+
+jest.setTimeout(30_000);
+
+describe('desktop-driver CLI', () => {
+  test('serves, lists, runs, and describes a fake authored plan as JSON', async () => {
+    const port = await getAvailablePort();
+    const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-driver-cli-'));
+    const artifactsRoot = path.join(temporaryDirectory, 'artifacts');
+    const manifestPath = path.join(temporaryDirectory, 'manifest.json');
+    const manifest: DesktopStoryManifest = {
+      endpoint: 'windows',
+      entries: [
+        {
+          id: 'components-button--default',
+          name: 'Default',
+          packageName: '@fluentui-react-native/components',
+          sourcePath: 'src/components/button/button.stories.tsx',
+          tags: ['e2e', 'story'],
+          tests: {
+            version: 1,
+            tests: [
+              {
+                id: 'cli-plan',
+                steps: [{ expect: { state: 'enabled', target: { testId: 'button-primary' }, value: true } }],
+              },
+            ],
+          },
+          title: 'Components/Button',
+        },
+      ],
+      platformManifestDigest: 'platform-digest',
+      portablePlanDigest: 'portable-digest',
+      schemaVersion: 1,
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest));
+    const server = spawnCli(['serve', '--port', String(port), '--target', 'cli-target', '--manifest', manifestPath]);
+    try {
+      await waitForResponse(loopbackUrl(port, '/status'));
+      const url = loopbackUrl(port, '');
+      const stories = await runCli(['stories', 'list', '--url', url, '--target', 'cli-target']);
+      expect(stories).toMatchObject({ entries: [{ id: 'components-button--default' }] });
+
+      const result = await runCli([
+        'stories',
+        'run',
+        '--url',
+        url,
+        '--target',
+        'cli-target',
+        '--artifacts',
+        artifactsRoot,
+        '--test',
+        'cli-plan',
+      ]);
+      expect(result).toMatchObject({ status: 'passed', tests: [{ testId: 'cli-plan' }] });
+
+      const tree = await runCli([
+        'agent',
+        'describe',
+        '--url',
+        url,
+        '--target',
+        'cli-target',
+        '--artifacts',
+        artifactsRoot,
+        '--scope',
+        'story',
+      ]);
+      expect(tree).toMatchObject([{ testId: 'story-root' }]);
+    } finally {
+      server.kill();
+      await waitForExit(server);
+      fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+    }
+  });
+});
+
+function spawnCli(args: readonly string[]) {
+  return spawn(process.execPath, [path.resolve(__dirname, '../../config/cli.cjs'), ...args], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function runCli(args: readonly string[]): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const child = spawnCli(args);
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    child.stdout.on('data', (chunk: Buffer) => stdout.push(chunk));
+    child.stderr.on('data', (chunk: Buffer) => stderr.push(chunk));
+    child.once('error', reject);
+    child.once('exit', (code) => {
+      if (code !== 0) {
+        reject(new Error(Buffer.concat(stderr).toString('utf8') || `Desktop Driver CLI exited with code ${code}.`));
+        return;
+      }
+      resolve(JSON.parse(Buffer.concat(stdout).toString('utf8')) as Record<string, unknown>);
+    });
+  });
+}
+
+function getAvailablePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        reject(new Error('Could not allocate a loopback port.'));
+        return;
+      }
+      server.close((error) => (error ? reject(error) : resolve(address.port)));
+    });
+  });
+}
+
+async function waitForResponse(url: string): Promise<void> {
+  const deadline = Date.now() + 20_000;
+  do {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        return;
+      }
+    } catch {
+      // Retry until the bounded startup deadline.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  } while (Date.now() < deadline);
+  throw new Error(`Timed out waiting for ${url}.`);
+}
+
+function waitForExit(child: ReturnType<typeof spawn>): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => child.once('exit', () => resolve()));
+}
+
+function loopbackUrl(port: number, pathname: string): string {
+  // eslint-disable-next-line @microsoft/sdl/no-insecure-url -- test-only loopback service
+  return `http://127.0.0.1:${port}${pathname}`;
+}

package/src/cli/createDesktopDriverCommand.ts

@@ -0,0 +1,290 @@
+import fs from 'node:fs';
+
+import { Command, Option } from 'commander';
+
+import { connectDesktopAgent } from '../agent/DesktopAgent.js';
+import { validateDesktopStoryTests } from '../authoring/storyTests.js';
+import type { DesktopStoryManifest } from '../storybook.js';
+import { FakeDesktopHost } from '../hosts/fake/FakeDesktopHost.js';
+import type { DesktopEndpoint, DesktopPlatformName, DesktopRenderer } from '../protocol/types.js';
+import { createDesktopDriverServer } from '../server/createDesktopDriverServer.js';
+import { FakeStoryOrchestrator } from '../testing/FakeStoryOrchestrator.js';
+import { createFakeStoryWindows } from '../testing/fakeStoryElements.js';
+import { connectDesktopWebdriver } from '../wdio/DesktopWebdriver.js';
+
+type ConnectionFlags = {
+  artifacts?: string;
+  platform: DesktopPlatformName;
+  target: string;
+  url: string;
+};
+
+type SelectionFlags = ConnectionFlags & {
+  shardCount?: number;
+  shardIndex?: number;
+  story?: string;
+  tag?: string;
+  test?: string;
+};
+
+export type CreateDesktopDriverCommandOptions = {
+  stderr?: Pick<NodeJS.WriteStream, 'write'>;
+  stdout?: Pick<NodeJS.WriteStream, 'write'>;
+};
+
+export function createDesktopDriverCommand(options: CreateDesktopDriverCommandOptions = {}): Command {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const program = new Command()
+    .name('desktop-driver')
+    .description('Drive React Native desktop applications through W3C WebDriver without Appium.')
+    .configureOutput({
+      writeErr: (value) => stderr.write(value),
+      writeOut: (value) => stdout.write(value),
+    });
+
+  program
+    .command('serve')
+    .description('Start a deterministic fake Desktop Driver target.')
+    .option('--host <host>', 'loopback host', '127.0.0.1')
+    .option('--port <port>', 'listener port; defaults to an available port', parsePort)
+    .option('--target <id>', 'registered target id', 'desktop-driver-fake')
+    .addOption(new Option('--platform <name>', 'WebDriver platform name').choices(['macos', 'windows']).default('windows'))
+    .addOption(new Option('--endpoint <name>', 'desktop endpoint').choices(['macos', 'windows', 'win32']).default('windows'))
+    .addOption(new Option('--renderer <name>', 'React Native renderer').choices(['fabric', 'paper']).default('fabric'))
+    .option('--manifest <path>', 'optional Story Manifest for fake story orchestration')
+    .action(async (flags) => {
+      const manifest = flags.manifest ? readManifest(flags.manifest) : undefined;
+      const host = new FakeDesktopHost({
+        endpoint: flags.endpoint as DesktopEndpoint,
+        platformName: flags.platform as DesktopPlatformName,
+        ...(manifest ? { storyRootTestId: 'story-root' } : {}),
+        ...(manifest ? { windows: createFakeStoryWindows(manifest) } : {}),
+      });
+      const storyOrchestrator = manifest ? new FakeStoryOrchestrator(manifest, host) : undefined;
+      const server = await createDesktopDriverServer({
+        host: flags.host,
+        port: flags.port,
+        targets: [
+          {
+            endpoint: flags.endpoint as DesktopEndpoint,
+            host,
+            id: flags.target,
+            platformName: flags.platform as DesktopPlatformName,
+            renderer: flags.renderer as DesktopRenderer,
+            ...(storyOrchestrator ? { storyOrchestrator, storyRootTestId: 'story-root' } : {}),
+          },
+        ],
+      });
+      writeJson(stdout, { server: server.url, targetId: flags.target });
+      try {
+        await waitForSignal();
+      } finally {
+        await server.close();
+      }
+    });
+
+  const stories = program.command('stories').description('Inspect or run authored desktop story tests.');
+  addConnectionOptions(
+    stories
+      .command('list')
+      .description('List stories and tests from the active platform manifest.')
+      .action(async (flags: ConnectionFlags) => {
+        const desktop = await connect(flags);
+        try {
+          writeJson(stdout, await desktop.listStories());
+        } finally {
+          await desktop.delete();
+        }
+      }),
+  );
+  addConnectionOptions(
+    stories
+      .command('explain')
+      .description('Print one story and its authored test plans.')
+      .argument('<storyId>')
+      .action(async (storyId: string, flags: ConnectionFlags) => {
+        const desktop = await connect(flags);
+        try {
+          const story = (await desktop.listStories()).entries.find(({ id }) => id === storyId);
+          if (!story) {
+            throw new Error(`Story "${storyId}" is not present in the active manifest.`);
+          }
+          writeJson(stdout, story);
+        } finally {
+          await desktop.delete();
+        }
+      }),
+  );
+  addSelectionOptions(
+    addConnectionOptions(
+      stories
+        .command('run')
+        .description('Run selected authored plans through WebdriverIO.')
+        .requiredOption('--artifacts <path>', 'artifact and report root')
+        .action(async (flags: SelectionFlags) => {
+          const artifactsRoot = requireOption(flags.artifacts, '--artifacts');
+          const desktop = await connect(flags);
+          try {
+            const result = await desktop.runStoryTests({
+              artifactsRoot,
+              selection: {
+                shardCount: flags.shardCount,
+                shardIndex: flags.shardIndex,
+                story: flags.story,
+                tag: flags.tag,
+                test: flags.test,
+              },
+            });
+            writeJson(stdout, result);
+            if (result.status !== 'passed') {
+              process.exitCode = 1;
+            }
+          } finally {
+            await desktop.delete();
+          }
+        }),
+    ),
+  );
+
+  const agent = program.command('agent').description('Use bounded JSON-safe agent operations.');
+  addConnectionOptions(
+    agent
+      .command('describe')
+      .description('Print a bounded accessibility-tree projection.')
+      .requiredOption('--artifacts <path>', 'artifact root')
+      .option('--depth <depth>', 'maximum tree depth', parseNonNegativeInteger, 3)
+      .option('--max-nodes <count>', 'maximum returned nodes', parsePositiveInteger, 100)
+      .addOption(new Option('--scope <scope>', 'tree scope').choices(['application', 'story']).default('story'))
+      .action(async (flags: ConnectionFlags & { depth: number; maxNodes: number; scope: 'application' | 'story' }) => {
+        const artifactsRoot = requireOption(flags.artifacts, '--artifacts');
+        const desktopAgent = await connectDesktopAgent({
+          artifactsRoot,
+          platformName: flags.platform,
+          targetId: flags.target,
+          url: flags.url,
+        });
+        try {
+          writeJson(stdout, await desktopAgent.describe({ depth: flags.depth, maxNodes: flags.maxNodes, scope: flags.scope }));
+        } finally {
+          await desktopAgent.delete();
+        }
+      }),
+  );
+  addConnectionOptions(
+    agent
+      .command('screenshot')
+      .description('Capture a named screenshot artifact.')
+      .requiredOption('--artifacts <path>', 'artifact root')
+      .requiredOption('--name <name>', 'artifact name')
+      .action(async (flags: ConnectionFlags & { name: string }) => {
+        const artifactsRoot = requireOption(flags.artifacts, '--artifacts');
+        const desktopAgent = await connectDesktopAgent({
+          artifactsRoot,
+          platformName: flags.platform,
+          targetId: flags.target,
+          url: flags.url,
+        });
+        try {
+          writeJson(stdout, await desktopAgent.screenshot(flags.name));
+        } finally {
+          await desktopAgent.delete();
+        }
+      }),
+  );
+
+  return program;
+}
+
+export async function runDesktopDriverCli(argv: readonly string[] = process.argv): Promise<void> {
+  await createDesktopDriverCommand().parseAsync([...argv]);
+}
+
+function addConnectionOptions<T extends Command>(command: T): T {
+  return command
+    .requiredOption('--url <url>', 'Desktop Driver server URL')
+    .requiredOption('--target <id>', 'registered target id')
+    .addOption(new Option('--platform <name>', 'WebDriver platform name').choices(['macos', 'windows']).default('windows')) as T;
+}
+
+function addSelectionOptions<T extends Command>(command: T): T {
+  return command
+    .option('--story <pattern>', 'story id glob')
+    .option('--test <pattern>', 'test id glob')
+    .option('--tag <tag>', 'required story tag')
+    .option('--shard-index <index>', 'zero-based shard index', parseNonNegativeInteger)
+    .option('--shard-count <count>', 'number of shards', parsePositiveInteger) as T;
+}
+
+function connect(flags: ConnectionFlags) {
+  return connectDesktopWebdriver({
+    platformName: flags.platform,
+    targetId: flags.target,
+    url: flags.url,
+  });
+}
+
+function readManifest(manifestPath: string): DesktopStoryManifest {
+  const value = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as DesktopStoryManifest;
+  if (
+    value.schemaVersion !== 1 ||
+    !Array.isArray(value.entries) ||
+    (value.endpoint !== 'macos' && value.endpoint !== 'windows' && value.endpoint !== 'win32') ||
+    typeof value.platformManifestDigest !== 'string' ||
+    typeof value.portablePlanDigest !== 'string'
+  ) {
+    throw new Error(`Invalid Desktop Story Manifest at ${manifestPath}.`);
+  }
+  for (const entry of value.entries) {
+    if (!entry || typeof entry.id !== 'string' || !Array.isArray(entry.tags)) {
+      throw new Error(`Invalid Desktop Story Manifest entry at ${manifestPath}.`);
+    }
+    if (entry.tests) {
+      validateDesktopStoryTests(entry.tests, `${manifestPath}#${entry.id}`);
+    }
+  }
+  return value;
+}
+
+function writeJson(output: Pick<NodeJS.WriteStream, 'write'>, value: unknown): void {
+  output.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function waitForSignal(): Promise<void> {
+  return new Promise((resolve) => {
+    process.once('SIGINT', resolve);
+    process.once('SIGTERM', resolve);
+  });
+}
+
+function parsePort(value: string): number {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new TypeError(`Port must be an integer between 0 and 65535. Received "${value}".`);
+  }
+
+  return port;
+}
+
+function requireOption(value: string | undefined, name: string): string {
+  if (!value) {
+    throw new TypeError(`${name} requires a non-empty value.`);
+  }
+  return value;
+}
+
+function parseNonNegativeInteger(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new TypeError(`Expected a non-negative integer. Received "${value}".`);
+  }
+  return parsed;
+}
+
+function parsePositiveInteger(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new TypeError(`Expected a positive integer. Received "${value}".`);
+  }
+  return parsed;
+}

package/src/cli/index.ts

@@ -0,0 +1,2 @@
+export { createDesktopDriverCommand, runDesktopDriverCli } from './createDesktopDriverCommand.js';
+export type { CreateDesktopDriverCommandOptions } from './createDesktopDriverCommand.js';

package/src/client/DesktopDriverClient.ts

@@ -0,0 +1,218 @@
+import { randomUUID } from 'node:crypto';
+
+import { WebDriverError } from '../protocol/errors.js';
+import { webElementIdentifier } from '../protocol/constants.js';
+import type { DesktopTreeNode } from '../host/types.js';
+import type {
+  NewSessionCapabilities,
+  WebDriverActionSequence,
+  WebDriverElement,
+  WebDriverErrorResponse,
+  WebDriverResponse,
+  WebDriverTimeouts,
+} from '../protocol/types.js';
+import type { DesktopStoryManifest, StoryReadyResult } from '../storybook.js';
+
+export type DesktopDriverClientOptions = {
+  fetch?: typeof globalThis.fetch;
+  url: string;
+};
+
+export class DesktopDriverClient {
+  private readonly fetch: typeof globalThis.fetch;
+  private readonly url: string;
+
+  constructor({ fetch = globalThis.fetch, url }: DesktopDriverClientOptions) {
+    this.fetch = fetch;
+    this.url = url.replace(/\/$/, '');
+  }
+
+  status(): Promise<Record<string, unknown>> {
+    return this.request('GET', '/status');
+  }
+
+  async newSession(capabilities: NewSessionCapabilities): Promise<DesktopSessionClient> {
+    const value = await this.request<{ capabilities: Record<string, unknown>; sessionId: string }>('POST', '/session', {
+      capabilities,
+    });
+    return new DesktopSessionClient(this, value.sessionId, value.capabilities);
+  }
+
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const response = await this.fetch(`${this.url}${path}`, {
+      method,
+      ...(body === undefined
+        ? {}
+        : {
+            body: JSON.stringify(body),
+            headers: { 'Content-Type': 'application/json' },
+          }),
+    });
+    const payload = (await response.json()) as WebDriverResponse<T> | WebDriverErrorResponse;
+    if (!response.ok) {
+      const error = payload.value as WebDriverErrorResponse['value'];
+      throw new WebDriverError(error.error as ConstructorParameters<typeof WebDriverError>[0], error.message, error.data);
+    }
+    return payload.value as T;
+  }
+}
+
+export class DesktopSessionClient {
+  private readonly driver: DesktopDriverClient;
+  readonly id: string;
+  readonly capabilities: Readonly<Record<string, unknown>>;
+
+  constructor(driver: DesktopDriverClient, id: string, capabilities: Readonly<Record<string, unknown>>) {
+    this.driver = driver;
+    this.id = id;
+    this.capabilities = capabilities;
+  }
+
+  delete(): Promise<null> {
+    return this.command('DELETE', '');
+  }
+
+  getTimeouts(): Promise<WebDriverTimeouts> {
+    return this.command('GET', '/timeouts');
+  }
+
+  setTimeouts(timeouts: Partial<WebDriverTimeouts>): Promise<null> {
+    return this.command('POST', '/timeouts', timeouts);
+  }
+
+  getWindowHandle(): Promise<string> {
+    return this.command('GET', '/window');
+  }
+
+  getWindowHandles(): Promise<string[]> {
+    return this.command('GET', '/window/handles');
+  }
+
+  switchToWindow(handle: string): Promise<null> {
+    return this.command('POST', '/window', { handle });
+  }
+
+  findElement(using: string, value: string): Promise<DesktopElementClient> {
+    return this.command<WebDriverElement>('POST', '/element', { using, value }).then(
+      (element) => new DesktopElementClient(this, element[webElementIdentifier]),
+    );
+  }
+
+  findElements(using: string, value: string): Promise<DesktopElementClient[]> {
+    return this.command<WebDriverElement[]>('POST', '/elements', { using, value }).then((elements) =>
+      elements.map((element) => new DesktopElementClient(this, element[webElementIdentifier])),
+    );
+  }
+
+  getActiveElement(): Promise<DesktopElementClient | null> {
+    return this.command<WebDriverElement | null>('GET', '/element/active').then((element) =>
+      element ? new DesktopElementClient(this, element[webElementIdentifier]) : null,
+    );
+  }
+
+  performActions(actions: readonly WebDriverActionSequence[]): Promise<null> {
+    return this.command('POST', '/actions', { actions });
+  }
+
+  releaseActions(): Promise<null> {
+    return this.command('DELETE', '/actions');
+  }
+
+  takeScreenshot(): Promise<string> {
+    return this.command('GET', '/screenshot');
+  }
+
+  getPageSource(): Promise<string> {
+    return this.command('GET', '/source');
+  }
+
+  getTree(): Promise<DesktopTreeNode[]> {
+    return this.command('GET', '/furn/tree');
+  }
+
+  getStoryManifest(): Promise<DesktopStoryManifest> {
+    return this.command('GET', '/furn/manifest');
+  }
+
+  getCurrentStory(): Promise<StoryReadyResult | null> {
+    return this.command('GET', '/furn/story');
+  }
+
+  selectStory(storyId: string, runId: string = randomUUID()): Promise<StoryReadyResult> {
+    return this.command('POST', '/furn/story', { requestId: randomUUID(), runId, storyId });
+  }
+
+  resetStory(storyId: string, runId: string = randomUUID()): Promise<StoryReadyResult> {
+    return this.command('POST', '/furn/story/reset', { requestId: randomUUID(), runId, storyId });
+  }
+
+  updateStoryArgs(storyId: string, args: Readonly<Record<string, unknown>>): Promise<null> {
+    return this.command('POST', '/furn/story/args', { args, storyId });
+  }
+
+  command<T>(method: string, path: string, body?: unknown): Promise<T> {
+    return this.driver.request(method, `/session/${this.id}${path}`, body);
+  }
+}
+
+export class DesktopElementClient {
+  private readonly session: DesktopSessionClient;
+  readonly id: string;
+
+  constructor(session: DesktopSessionClient, id: string) {
+    this.session = session;
+    this.id = id;
+  }
+
+  click(): Promise<null> {
+    return this.command('POST', '/click', {});
+  }
+
+  clear(): Promise<null> {
+    return this.command('POST', '/clear', {});
+  }
+
+  sendKeys(text: string): Promise<null> {
+    return this.command('POST', '/value', { text });
+  }
+
+  getText(): Promise<string> {
+    return this.command('GET', '/text');
+  }
+
+  getTagName(): Promise<string> {
+    return this.command('GET', '/name');
+  }
+
+  isEnabled(): Promise<boolean> {
+    return this.command('GET', '/enabled');
+  }
+
+  isDisplayed(): Promise<boolean> {
+    return this.command('GET', '/displayed');
+  }
+
+  isSelected(): Promise<boolean> {
+    return this.command('GET', '/selected');
+  }
+
+  getAttribute(name: string): Promise<unknown> {
+    return this.command('GET', `/attribute/${encodeURIComponent(name)}`);
+  }
+
+  getProperty(name: string): Promise<unknown> {
+    return this.command('GET', `/property/${encodeURIComponent(name)}`);
+  }
+
+  takeScreenshot(): Promise<string> {
+    return this.command('GET', '/screenshot');
+  }
+
+  private command<T>(method: string, path: string, body?: unknown): Promise<T> {
+    return this.session.command(method, `/element/${this.id}${path}`, body);
+  }
+}
+
+export function createDesktopDriverClient(options: DesktopDriverClientOptions): DesktopDriverClient {
+  return new DesktopDriverClient(options);
+}

package/src/client/index.ts

@@ -0,0 +1,2 @@
+export { createDesktopDriverClient, DesktopDriverClient, DesktopElementClient, DesktopSessionClient } from './DesktopDriverClient.js';
+export type { DesktopDriverClientOptions } from './DesktopDriverClient.js';