@fluentui-react-native/desktop-driver 0.2.0

package/src/testing/fakeStoryElements.ts

@@ -0,0 +1,167 @@
+import type { DesktopStoryExpectation, DesktopStorySelector, DesktopStoryStep } from '../authoring/storyTests.js';
+import type { FakeDesktopElement, FakeDesktopWindow } from '../hosts/fake/FakeDesktopHost.js';
+import type { DesktopStoryManifest } from '../storybook.js';
+
+type MutableFakeElement = Omit<FakeDesktopElement, 'rect'> & {
+  rect: FakeDesktopElement['rect'];
+};
+
+export function createFakeStoryWindows(manifest: DesktopStoryManifest, storyRootTestId = 'story-root'): FakeDesktopWindow[] {
+  const windowId = 'window-1';
+  const windowRect = { height: 600, width: 800, x: 0, y: 0 };
+  const elements = new Map<string, MutableFakeElement>();
+  let elementIndex = 0;
+
+  for (const entry of manifest.entries) {
+    for (const test of entry.tests?.tests ?? []) {
+      const mutated = new Set<string>();
+      for (const step of test.steps) {
+        if ('expect' in step) {
+          applyExpectation(elements, step.expect, mutated, windowId, () => elementIndex++);
+        } else {
+          for (const selector of stepSelectors(step)) {
+            ensureElement(elements, selector, windowId, () => elementIndex++);
+          }
+          markMutated(step, mutated);
+        }
+      }
+    }
+  }
+
+  return [
+    {
+      elements: [
+        {
+          automationId: 'app-root',
+          id: 'root',
+          rect: windowRect,
+          role: 'application',
+          scope: 'application',
+          windowId,
+        },
+        {
+          automationId: storyRootTestId,
+          id: 'story-root',
+          name: JSON.stringify({ previewGeneration: 0, storyId: 'initial--story' }),
+          parentId: 'root',
+          rect: windowRect,
+          role: 'group',
+          scope: 'preview',
+          windowId,
+        },
+        ...elements.values(),
+      ],
+      id: windowId,
+      rect: windowRect,
+      title: 'Desktop Driver Storybook Fake Target',
+    },
+  ];
+}
+
+function applyExpectation(
+  elements: Map<string, MutableFakeElement>,
+  expectation: DesktopStoryExpectation,
+  mutated: ReadonlySet<string>,
+  windowId: string,
+  nextIndex: () => number,
+): void {
+  const element = ensureElement(elements, expectation.target, windowId, nextIndex);
+  if (mutated.has(selectorIdentity(expectation.target))) {
+    return;
+  }
+  switch (expectation.state) {
+    case 'accessibleName':
+      element.name = expectation.value as string;
+      break;
+    case 'checked':
+      element.checked = expectation.value as boolean | 'mixed';
+      break;
+    case 'displayed':
+      element.visible = expectation.value === undefined ? true : (expectation.value as boolean);
+      break;
+    case 'enabled':
+      element.enabled = expectation.value === undefined ? true : (expectation.value as boolean);
+      break;
+    case 'expanded':
+      element.expanded = expectation.value === undefined ? true : (expectation.value as boolean);
+      break;
+    case 'focused':
+      element.focused = expectation.value === undefined ? true : (expectation.value as boolean);
+      break;
+    case 'role':
+      element.role = expectation.value as string;
+      break;
+    case 'selected':
+      element.selected = expectation.value === undefined ? true : (expectation.value as boolean);
+      break;
+    case 'text':
+      element.text = expectation.value as string;
+      break;
+    case 'value':
+      element.value = expectation.value as string;
+      break;
+    case 'count':
+    case 'exists':
+      break;
+  }
+}
+
+function ensureElement(
+  elements: Map<string, MutableFakeElement>,
+  selector: DesktopStorySelector,
+  windowId: string,
+  nextIndex: () => number,
+): MutableFakeElement {
+  const identity = selectorIdentity(selector);
+  const existing = elements.get(identity);
+  if (existing) {
+    return existing;
+  }
+  const index = nextIndex();
+  const element: MutableFakeElement = {
+    id: `story-element-${index}`,
+    parentId: 'story-root',
+    rect: { height: 36, width: 180, x: 16, y: 16 + index * 44 },
+    role: 'group',
+    scope: 'preview',
+    windowId,
+    ...('testId' in selector ? { automationId: selector.testId } : {}),
+    ...('accessibleName' in selector ? { name: selector.accessibleName } : {}),
+    ...('role' in selector ? { name: selector.name, role: selector.role } : {}),
+    ...('text' in selector ? { name: selector.text, text: selector.text } : {}),
+  };
+  elements.set(identity, element);
+  return element;
+}
+
+function selectorIdentity(selector: DesktopStorySelector): string {
+  if ('testId' in selector) {
+    return `testId:${selector.testId}`;
+  }
+  if ('role' in selector) {
+    return `role:${selector.role}:${selector.name ?? ''}`;
+  }
+  if ('accessibleName' in selector) {
+    return `name:${selector.accessibleName}`;
+  }
+  return `text:${selector.text}`;
+}
+
+function stepSelectors(step: Exclude<DesktopStoryStep, { expect: DesktopStoryExpectation }>): DesktopStorySelector[] {
+  if ('target' in step && step.target) {
+    return [step.target];
+  }
+  if (step.action === 'wait' && step.until) {
+    return [step.until.target];
+  }
+  return [];
+}
+
+function markMutated(step: Exclude<DesktopStoryStep, { expect: DesktopStoryExpectation }>, mutated: Set<string>): void {
+  if (!('target' in step) || !step.target) {
+    return;
+  }
+  if (step.action === 'click' || step.action === 'doubleClick' || step.action === 'clear' || step.action === 'type') {
+    mutated.add(selectorIdentity(step.target));
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,6 @@
+export { FakeDesktopHost } from '../hosts/fake/FakeDesktopHost.js';
+export type { FakeDesktopElement, FakeDesktopHostOptions, FakeDesktopWindow } from '../hosts/fake/FakeDesktopHost.js';
+export { createDesktopDriverStoryHarness, createDesktopDriverTestHarness } from './protocolHarness.js';
+export type { DesktopDriverTestHarness } from './protocolHarness.js';
+export { FakeStoryOrchestrator } from './FakeStoryOrchestrator.js';
+export { createFakeStoryWindows } from './fakeStoryElements.js';

package/src/testing/protocolHarness.ts

@@ -0,0 +1,66 @@
+import { FakeDesktopHost } from '../hosts/fake/FakeDesktopHost.js';
+import type { FakeDesktopHostOptions } from '../hosts/fake/FakeDesktopHost.js';
+import type { DesktopTarget } from '../host/types.js';
+import { createDesktopDriverServer } from '../server/createDesktopDriverServer.js';
+import type { DesktopDriverServer } from '../server/createDesktopDriverServer.js';
+import type { StoryOrchestrator } from '../storybook.js';
+import type { DesktopStoryManifest } from '../storybook.js';
+import { FakeStoryOrchestrator } from './FakeStoryOrchestrator.js';
+
+export type DesktopDriverTestHarness = {
+  host: FakeDesktopHost;
+  storyOrchestrator?: FakeStoryOrchestrator;
+  server: DesktopDriverServer;
+  target: DesktopTarget;
+  close(): Promise<void>;
+};
+
+export async function createDesktopDriverTestHarness(
+  options: FakeDesktopHostOptions = {},
+  storyOrchestrator?: StoryOrchestrator,
+): Promise<DesktopDriverTestHarness> {
+  const host = new FakeDesktopHost(options);
+  const endpoint = options.endpoint ?? 'windows';
+  const target: DesktopTarget = {
+    endpoint,
+    host,
+    id: `fake-${endpoint}`,
+    platformName: options.platformName ?? (endpoint === 'macos' ? 'macos' : 'windows'),
+    renderer: endpoint === 'win32' ? 'paper' : 'fabric',
+    ...(storyOrchestrator ? { storyRootTestId: 'story-root' } : {}),
+    storyOrchestrator,
+  };
+  const server = await createDesktopDriverServer({ targets: [target] });
+  return {
+    host,
+    server,
+    target,
+    close: () => server.close(),
+  };
+}
+
+export async function createDesktopDriverStoryHarness(
+  manifest: DesktopStoryManifest,
+  options: FakeDesktopHostOptions = {},
+): Promise<DesktopDriverTestHarness> {
+  const host = new FakeDesktopHost({ ...options, storyRootTestId: 'story-root' });
+  const storyOrchestrator = new FakeStoryOrchestrator(manifest, host);
+  const endpoint = options.endpoint ?? manifest.endpoint;
+  const target: DesktopTarget = {
+    endpoint,
+    host,
+    id: `fake-${endpoint}`,
+    platformName: options.platformName ?? (endpoint === 'macos' ? 'macos' : 'windows'),
+    renderer: endpoint === 'win32' ? 'paper' : 'fabric',
+    storyOrchestrator,
+    storyRootTestId: 'story-root',
+  };
+  const server = await createDesktopDriverServer({ targets: [target] });
+  return {
+    host,
+    server,
+    storyOrchestrator,
+    target,
+    close: () => server.close(),
+  };
+}

package/src/wdio/DesktopWebdriver.test.ts

@@ -0,0 +1,76 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { DesktopStoryManifest } from '../storybook.js';
+import { createDesktopDriverStoryHarness } from '../testing/protocolHarness.js';
+
+describe('sanctioned WebdriverIO API', () => {
+  test('lists and runs an authored plan through registered browser commands', async () => {
+    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: 'click',
+                steps: [
+                  { action: 'click', target: { testId: 'button-primary' } },
+                  { expect: { state: 'focused', target: { testId: 'button-primary' }, value: true } },
+                ],
+              },
+            ],
+          },
+          title: 'Components/Button',
+        },
+      ],
+      platformManifestDigest: 'platform-digest',
+      portablePlanDigest: 'portable-digest',
+      schemaVersion: 1,
+    };
+    const harness = await createDesktopDriverStoryHarness(manifest);
+    const artifactsRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-driver-wdio-'));
+    try {
+      const response = await runContract(harness.server.url, harness.target.id, artifactsRoot);
+      expect(response).toMatchObject({
+        manifestEntries: 1,
+        result: {
+          status: 'passed',
+          tests: [{ status: 'passed', storyId: 'components-button--default', testId: 'click' }],
+        },
+      });
+      expect(fs.existsSync(path.join(artifactsRoot, 'run.json'))).toBe(true);
+    } finally {
+      await harness.close();
+      fs.rmSync(artifactsRoot, { force: true, recursive: true });
+    }
+  });
+});
+
+function runContract(url: string, targetId: string, artifactsRoot: string): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [path.join(__dirname, 'wdioRunner.contract.cjs'), url, targetId, artifactsRoot], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    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') || `WebdriverIO runner exited with code ${code}.`));
+        return;
+      }
+      resolve(JSON.parse(Buffer.concat(stdout).toString('utf8')) as Record<string, unknown>);
+    });
+  });
+}

package/src/wdio/DesktopWebdriver.ts

@@ -0,0 +1,130 @@
+import { remote } from 'webdriverio';
+
+import type { DesktopStoryRunResult } from '../authoring/results.js';
+import type { DesktopStoryExpectation } from '../authoring/storyTests.js';
+import { ArtifactManager } from '../artifacts/ArtifactManager.js';
+import { createDesktopDriverClient, DesktopSessionClient } from '../client/DesktopDriverClient.js';
+import type { DesktopClickMode, DesktopPlatformName } from '../protocol/types.js';
+import { assertDesktopExpectation, runDesktopStoryTests } from '../runner/StoryTestRunner.js';
+import type { DesktopStoryTestSelection } from '../runner/StoryTestRunner.js';
+import type { DesktopStoryManifest, StoryReadyResult } from '../storybook.js';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace WebdriverIO {
+    interface Capabilities {
+      'furn:clickMode'?: 'accessibility' | 'auto' | 'physical';
+      'furn:endpoint'?: 'macos' | 'win32' | 'windows';
+      'furn:target'?: string;
+    }
+
+    interface Browser {
+      desktopListStories(): Promise<DesktopStoryManifest>;
+      desktopOpenStory(storyId: string, runId?: string): Promise<StoryReadyResult>;
+      desktopResetStory(storyId: string, runId?: string): Promise<StoryReadyResult>;
+      desktopExpect(expectation: DesktopStoryExpectation): Promise<void>;
+      desktopRunStoryTests(options?: DesktopWebdriverRunOptions): Promise<DesktopStoryRunResult>;
+    }
+  }
+}
+
+export type DesktopWebdriverOptions = {
+  clickMode?: DesktopClickMode;
+  logLevel?: 'debug' | 'error' | 'info' | 'silent' | 'trace' | 'warn';
+  platformName: DesktopPlatformName;
+  targetId: string;
+  url: string;
+};
+
+export type DesktopWebdriverRunOptions = {
+  artifactsRoot?: string;
+  selection?: DesktopStoryTestSelection;
+  signal?: AbortSignal;
+};
+
+export class DesktopWebdriverSession {
+  readonly browser: WebdriverIO.Browser;
+  readonly session: DesktopSessionClient;
+
+  constructor(browser: WebdriverIO.Browser, session: DesktopSessionClient) {
+    this.browser = browser;
+    this.session = session;
+  }
+
+  listStories(): Promise<DesktopStoryManifest> {
+    return this.session.getStoryManifest();
+  }
+
+  openStory(storyId: string, runId?: string): Promise<StoryReadyResult> {
+    return this.session.selectStory(storyId, runId);
+  }
+
+  resetStory(storyId: string, runId?: string): Promise<StoryReadyResult> {
+    return this.session.resetStory(storyId, runId);
+  }
+
+  expect(expectation: DesktopStoryExpectation): Promise<void> {
+    return assertDesktopExpectation(this.session, expectation);
+  }
+
+  async runStoryTests(options: DesktopWebdriverRunOptions = {}): Promise<DesktopStoryRunResult> {
+    const manifest = await this.session.getStoryManifest();
+    const endpoint = this.session.capabilities['furn:endpoint'];
+    const platformName = this.session.capabilities.platformName;
+    const targetId = this.session.capabilities['furn:target'];
+    if (
+      (endpoint !== 'macos' && endpoint !== 'windows' && endpoint !== 'win32') ||
+      (platformName !== 'macos' && platformName !== 'windows') ||
+      typeof targetId !== 'string'
+    ) {
+      throw new Error('Desktop Driver returned incomplete platform capabilities.');
+    }
+    return runDesktopStoryTests({
+      ...(options.artifactsRoot ? { artifacts: new ArtifactManager(options.artifactsRoot) } : {}),
+      endpoint,
+      manifest,
+      platformName,
+      selection: options.selection,
+      session: this.session,
+      signal: options.signal,
+      targetId,
+    });
+  }
+
+  async delete(): Promise<void> {
+    await this.browser.deleteSession();
+  }
+}
+
+export async function connectDesktopWebdriver(options: DesktopWebdriverOptions): Promise<DesktopWebdriverSession> {
+  const url = new URL(options.url);
+  const capabilities = Object.assign(
+    {
+      browserName: 'furn-native-desktop',
+      platformName: options.platformName,
+    },
+    {
+      'furn:clickMode': options.clickMode ?? 'auto',
+      'furn:target': options.targetId,
+    },
+  );
+  const browser = await remote({
+    capabilities,
+    hostname: url.hostname,
+    logLevel: options.logLevel ?? 'silent',
+    path: url.pathname === '/' ? '/' : url.pathname,
+    port: Number(url.port),
+    protocol: url.protocol.replace(':', '') as 'http' | 'https',
+  });
+  const client = createDesktopDriverClient({ url: options.url });
+  const session = new DesktopSessionClient(client, browser.sessionId, Object.fromEntries(Object.entries(browser.capabilities)));
+  const desktop = new DesktopWebdriverSession(browser, session);
+
+  browser.addCommand('desktopListStories', () => desktop.listStories());
+  browser.addCommand('desktopOpenStory', (storyId: string, runId?: string) => desktop.openStory(storyId, runId));
+  browser.addCommand('desktopResetStory', (storyId: string, runId?: string) => desktop.resetStory(storyId, runId));
+  browser.addCommand('desktopExpect', (expectation: DesktopStoryExpectation) => desktop.expect(expectation));
+  browser.addCommand('desktopRunStoryTests', (runOptions?: DesktopWebdriverRunOptions) => desktop.runStoryTests(runOptions));
+
+  return desktop;
+}

package/src/wdio/index.ts

@@ -0,0 +1,2 @@
+export { connectDesktopWebdriver, DesktopWebdriverSession } from './DesktopWebdriver.js';
+export type { DesktopWebdriverOptions, DesktopWebdriverRunOptions } from './DesktopWebdriver.js';

package/src/wdio/wdioRunner.contract.cjs

@@ -0,0 +1,30 @@
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+async function main() {
+  const moduleUrl = pathToFileURL(path.resolve(__dirname, '..', '..', 'lib', 'wdio', 'index.js')).href;
+  const { connectDesktopWebdriver } = await import(moduleUrl);
+  const [url, targetId, artifactsRoot] = process.argv.slice(2);
+  const desktop = await connectDesktopWebdriver({
+    platformName: 'windows',
+    targetId,
+    url,
+  });
+  try {
+    const manifest = await desktop.browser.desktopListStories();
+    await desktop.browser.desktopExpect({
+      state: 'enabled',
+      target: { testId: 'button-primary' },
+      value: true,
+    });
+    const result = await desktop.browser.desktopRunStoryTests({ artifactsRoot });
+    process.stdout.write(JSON.stringify({ manifestEntries: manifest.entries.length, result }));
+  } finally {
+    await desktop.delete();
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(error.stack ?? error.message);
+  process.exitCode = 1;
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "@fluentui-react-native/scripts/tsconfig",
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "src",
+    "composite": true,
+    "tsBuildInfoFile": ".cache/tsconfig.tsbuildinfo"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../scripts/tsconfig.json"
+    }
+  ]
+}