flow-walker-cli 0.2.0

package/src/yaml-writer.ts

@@ -0,0 +1,194 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Flow, FlowStep, ScreenEdge, ScreenNode } from './types.ts';
+import type { NavigationGraph } from './graph.ts';
+
+/**
+ * Generate YAML flow files from a navigation graph.
+ * Output matches sora's format: name, description, setup, steps[].
+ */
+export function generateFlows(graph: NavigationGraph): Flow[] {
+  const flows: Flow[] = [];
+
+  // Find root screens (screens with no incoming edges, or the first screen added)
+  const allTargets = new Set(graph.edges.map(e => e.target));
+  const roots = [...graph.nodes.values()].filter(n => !allTargets.has(n.id));
+
+  // If no clear root, use the first node
+  if (roots.length === 0 && graph.nodes.size > 0) {
+    roots.push(graph.nodes.values().next().value!);
+  }
+
+  // For each root, generate flows for each outgoing path
+  for (const root of roots) {
+    const outEdges = graph.edgesFrom(root.id);
+
+    if (outEdges.length === 0) {
+      // Single-screen flow
+      flows.push(buildSingleScreenFlow(root));
+      continue;
+    }
+
+    // One flow per outgoing branch from root
+    for (const edge of outEdges) {
+      const targetNode = graph.nodes.get(edge.target);
+      if (!targetNode) continue;
+
+      const flow = buildBranchFlow(root, edge, targetNode, graph);
+      flows.push(flow);
+    }
+  }
+
+  return flows;
+}
+
+function buildSingleScreenFlow(screen: ScreenNode): Flow {
+  return {
+    name: screen.name,
+    description: `Screen: ${screen.name} (${screen.elementCount} interactive elements)`,
+    setup: 'normal',
+    steps: [
+      {
+        name: `Snapshot ${screen.name}`,
+        assert: { interactive_count: { min: Math.max(1, screen.elementCount - 2) } },
+        screenshot: screen.name,
+      },
+    ],
+  };
+}
+
+function buildBranchFlow(
+  root: ScreenNode,
+  firstEdge: ScreenEdge,
+  firstTarget: ScreenNode,
+  graph: NavigationGraph,
+): Flow {
+  const steps: FlowStep[] = [];
+  const flowName = firstTarget.name;
+
+  // Step 1: snapshot root screen
+  steps.push({
+    name: `Verify ${root.name}`,
+    assert: { interactive_count: { min: Math.max(1, root.elementCount - 2) } },
+    screenshot: root.name,
+  });
+
+  // Step 2: press to navigate
+  steps.push({
+    name: `Press ${firstEdge.element.text || firstEdge.element.type}`,
+    press: {
+      type: firstEdge.element.type,
+      hint: firstEdge.element.text || undefined,
+    },
+    screenshot: firstTarget.name,
+  });
+
+  // Step 3: assert target screen
+  steps.push({
+    name: `Verify ${firstTarget.name}`,
+    assert: { interactive_count: { min: Math.max(1, firstTarget.elementCount - 2) } },
+  });
+
+  // Follow one more level of edges from target (if any)
+  const subEdges = graph.edgesFrom(firstTarget.id);
+  for (const subEdge of subEdges.slice(0, 3)) { // cap at 3 sub-branches per flow
+    const subTarget = graph.nodes.get(subEdge.target);
+    if (!subTarget || subTarget.id === root.id) continue;
+
+    steps.push({
+      name: `Press ${subEdge.element.text || subEdge.element.type}`,
+      press: {
+        type: subEdge.element.type,
+        hint: subEdge.element.text || undefined,
+      },
+      screenshot: subTarget.name,
+    });
+
+    steps.push({
+      name: `Back from ${subTarget.name}`,
+      back: true,
+    });
+  }
+
+  // Final step: back to root
+  steps.push({
+    name: `Back to ${root.name}`,
+    back: true,
+    assert: { interactive_count: { min: Math.max(1, root.elementCount - 2) } },
+  });
+
+  return {
+    name: flowName,
+    description: `${root.name} → ${firstTarget.name} navigation flow`,
+    setup: 'normal',
+    steps,
+  };
+}
+
+/** Serialize a Flow to YAML string (no library needed for this simple structure) */
+export function toYaml(flow: Flow): string {
+  const lines: string[] = [];
+
+  lines.push(`# E2E Flow: ${flow.name}`);
+  lines.push('');
+  lines.push(`name: ${flow.name}`);
+  lines.push(`description: ${flow.description}`);
+  lines.push(`setup: ${flow.setup}`);
+  lines.push('');
+  lines.push('steps:');
+
+  for (const step of flow.steps) {
+    lines.push(`  - name: ${step.name}`);
+
+    if (step.press) {
+      const parts = [`type: ${step.press.type}`];
+      if (step.press.hint) parts.push(`hint: "${step.press.hint}"`);
+      lines.push(`    press: { ${parts.join(', ')} }`);
+    }
+
+    if (step.scroll) {
+      lines.push(`    scroll: ${step.scroll}`);
+    }
+
+    if (step.back) {
+      lines.push(`    back: true`);
+    }
+
+    if (step.assert) {
+      const parts: string[] = [];
+      if (step.assert.interactive_count) {
+        parts.push(`interactive_count: { min: ${step.assert.interactive_count.min} }`);
+      }
+      if (step.assert.text) {
+        parts.push(`text: "${step.assert.text}"`);
+      }
+      if (parts.length > 0) {
+        lines.push(`    assert:`);
+        for (const part of parts) {
+          lines.push(`      ${part}`);
+        }
+      }
+    }
+
+    if (step.screenshot) {
+      lines.push(`    screenshot: ${step.screenshot}`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+/** Write all flows to the output directory */
+export function writeFlows(flows: Flow[], outputDir: string): string[] {
+  mkdirSync(outputDir, { recursive: true });
+  const written: string[] = [];
+
+  for (const flow of flows) {
+    const filename = `${flow.name}.yaml`;
+    const filepath = join(outputDir, filename);
+    writeFileSync(filepath, toYaml(flow));
+    written.push(filepath);
+  }
+
+  return written;
+}

package/tests/capture.test.ts

@@ -0,0 +1,75 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, rmdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureDir } from '../src/capture.ts';
+
+describe('ensureDir', () => {
+  const testBase = join(import.meta.dirname!, '..', '.test-tmp');
+
+  it('creates directory if it does not exist', () => {
+    const dir = join(testBase, 'ensureDir-new');
+    try { rmdirSync(dir, { recursive: true } as any); } catch {}
+    ensureDir(dir);
+    assert.ok(existsSync(dir));
+    rmdirSync(dir, { recursive: true } as any);
+  });
+
+  it('does not throw if directory already exists', () => {
+    const dir = join(testBase, 'ensureDir-exists');
+    mkdirSync(dir, { recursive: true });
+    assert.doesNotThrow(() => ensureDir(dir));
+    rmdirSync(dir, { recursive: true } as any);
+  });
+
+  it('creates nested directories', () => {
+    const dir = join(testBase, 'ensureDir-nested', 'a', 'b');
+    try { rmdirSync(join(testBase, 'ensureDir-nested'), { recursive: true } as any); } catch {}
+    ensureDir(dir);
+    assert.ok(existsSync(dir));
+    rmdirSync(join(testBase, 'ensureDir-nested'), { recursive: true } as any);
+  });
+
+  // Cleanup test base
+  it('cleanup', () => {
+    try { rmdirSync(testBase, { recursive: true } as any); } catch {}
+    assert.ok(true);
+  });
+});
+
+describe('capture module exports', () => {
+  it('exports screenshot function', async () => {
+    const mod = await import('../src/capture.ts');
+    assert.equal(typeof mod.screenshot, 'function');
+  });
+
+  it('exports startRecording function', async () => {
+    const mod = await import('../src/capture.ts');
+    assert.equal(typeof mod.startRecording, 'function');
+  });
+
+  it('exports stopRecording function', async () => {
+    const mod = await import('../src/capture.ts');
+    assert.equal(typeof mod.stopRecording, 'function');
+  });
+
+  it('exports startLogcat function', async () => {
+    const mod = await import('../src/capture.ts');
+    assert.equal(typeof mod.startLogcat, 'function');
+  });
+
+  it('exports stopLogcat function', async () => {
+    const mod = await import('../src/capture.ts');
+    assert.equal(typeof mod.stopLogcat, 'function');
+  });
+
+  it('exports getDeviceName function', async () => {
+    const mod = await import('../src/capture.ts');
+    assert.equal(typeof mod.getDeviceName, 'function');
+  });
+
+  it('exports ensureDir function', async () => {
+    const mod = await import('../src/capture.ts');
+    assert.equal(typeof mod.ensureDir, 'function');
+  });
+});

package/tests/command-schema.test.ts

@@ -0,0 +1,133 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { COMMAND_SCHEMAS, getCommandSchema, getSchemaEnvelope, SCHEMA_VERSION } from '../src/command-schema.ts';
+
+describe('COMMAND_SCHEMAS', () => {
+  it('contains walk, run, report, and schema commands', () => {
+    const names = COMMAND_SCHEMAS.map(s => s.name);
+    assert.ok(names.includes('walk'));
+    assert.ok(names.includes('run'));
+    assert.ok(names.includes('report'));
+    assert.ok(names.includes('schema'));
+  });
+
+  it('has exactly 4 commands', () => {
+    assert.equal(COMMAND_SCHEMAS.length, 4);
+  });
+
+  it('every schema has required fields', () => {
+    for (const schema of COMMAND_SCHEMAS) {
+      assert.ok(schema.name, `missing name`);
+      assert.ok(schema.description, `${schema.name}: missing description`);
+      assert.ok(Array.isArray(schema.args), `${schema.name}: args not array`);
+      assert.ok(Array.isArray(schema.flags), `${schema.name}: flags not array`);
+      assert.ok(typeof schema.exitCodes === 'object', `${schema.name}: exitCodes not object`);
+      assert.ok(Array.isArray(schema.examples), `${schema.name}: examples not array`);
+      assert.ok(schema.examples.length > 0, `${schema.name}: no examples`);
+    }
+  });
+
+  it('walk schema has --json and --dry-run flags', () => {
+    const walk = getCommandSchema('walk');
+    assert.ok(walk);
+    const flagNames = walk.flags.map(f => f.name);
+    assert.ok(flagNames.includes('--json'));
+    assert.ok(flagNames.includes('--dry-run'));
+  });
+
+  it('run schema has required flow arg', () => {
+    const run = getCommandSchema('run');
+    assert.ok(run);
+    assert.ok(run.args.some(a => a.name === 'flow' && a.required));
+  });
+
+  it('run schema has --dry-run flag', () => {
+    const run = getCommandSchema('run');
+    assert.ok(run);
+    assert.ok(run.flags.some(f => f.name === '--dry-run'));
+  });
+
+  it('run schema has exit code 1 for failing steps', () => {
+    const run = getCommandSchema('run');
+    assert.ok(run);
+    assert.ok(run.exitCodes['1']);
+  });
+
+  it('report schema has required run-dir arg', () => {
+    const report = getCommandSchema('report');
+    assert.ok(report);
+    assert.ok(report.args.some(a => a.name === 'run-dir' && a.required));
+  });
+
+  it('schema command has optional command arg', () => {
+    const schema = getCommandSchema('schema');
+    assert.ok(schema);
+    assert.ok(schema.args.some(a => a.name === 'command' && !a.required));
+  });
+
+  it('all exit codes include 0 and 2', () => {
+    for (const schema of COMMAND_SCHEMAS) {
+      assert.ok(schema.exitCodes['0'], `${schema.name}: missing exit code 0`);
+      assert.ok(schema.exitCodes['2'], `${schema.name}: missing exit code 2`);
+    }
+  });
+
+  it('every flag has a type field', () => {
+    const validTypes = ['string', 'boolean', 'integer', 'path'];
+    for (const schema of COMMAND_SCHEMAS) {
+      for (const flag of schema.flags) {
+        assert.ok(validTypes.includes(flag.type), `${schema.name} flag ${flag.name}: invalid type "${flag.type}"`);
+      }
+    }
+  });
+
+  it('every arg has a type field', () => {
+    const validTypes = ['string', 'path', 'integer'];
+    for (const schema of COMMAND_SCHEMAS) {
+      for (const arg of schema.args) {
+        assert.ok(validTypes.includes(arg.type), `${schema.name} arg ${arg.name}: invalid type "${arg.type}"`);
+      }
+    }
+  });
+
+  it('boolean flags have no default (they default to false)', () => {
+    for (const schema of COMMAND_SCHEMAS) {
+      for (const flag of schema.flags) {
+        if (flag.type === 'boolean') {
+          assert.equal(flag.default, undefined, `${schema.name} flag ${flag.name}: boolean should not have default`);
+        }
+      }
+    }
+  });
+});
+
+describe('getSchemaEnvelope', () => {
+  it('returns version and commands', () => {
+    const envelope = getSchemaEnvelope();
+    assert.ok(envelope.version);
+    assert.ok(Array.isArray(envelope.commands));
+    assert.equal(envelope.commands.length, COMMAND_SCHEMAS.length);
+  });
+
+  it('version matches SCHEMA_VERSION', () => {
+    const envelope = getSchemaEnvelope();
+    assert.equal(envelope.version, SCHEMA_VERSION);
+  });
+
+  it('version is semver format', () => {
+    assert.match(SCHEMA_VERSION, /^\d+\.\d+\.\d+$/);
+  });
+});
+
+describe('getCommandSchema', () => {
+  it('returns schema for known command', () => {
+    const schema = getCommandSchema('run');
+    assert.ok(schema);
+    assert.equal(schema.name, 'run');
+  });
+
+  it('returns undefined for unknown command', () => {
+    const schema = getCommandSchema('nonexistent');
+    assert.equal(schema, undefined);
+  });
+});

package/tests/errors.test.ts

@@ -0,0 +1,93 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { FlowWalkerError, ErrorCodes, formatError } from '../src/errors.ts';
+
+describe('FlowWalkerError', () => {
+  it('has code, message, and diagnosticId', () => {
+    const err = new FlowWalkerError(ErrorCodes.INVALID_INPUT, 'bad input');
+    assert.equal(err.code, 'INVALID_INPUT');
+    assert.equal(err.message, 'bad input');
+    assert.equal(typeof err.diagnosticId, 'string');
+    assert.equal(err.diagnosticId.length, 8);
+  });
+
+  it('includes hint when provided', () => {
+    const err = new FlowWalkerError(ErrorCodes.FILE_NOT_FOUND, 'not found', 'check path');
+    assert.equal(err.hint, 'check path');
+  });
+
+  it('generates unique diagnosticId per instance', () => {
+    const err1 = new FlowWalkerError(ErrorCodes.COMMAND_FAILED, 'a');
+    const err2 = new FlowWalkerError(ErrorCodes.COMMAND_FAILED, 'b');
+    assert.notEqual(err1.diagnosticId, err2.diagnosticId);
+  });
+
+  it('toJSON returns structured error envelope', () => {
+    const err = new FlowWalkerError(ErrorCodes.DEVICE_ERROR, 'device gone', 'check adb');
+    const json = err.toJSON();
+    assert.equal(json.error.code, 'DEVICE_ERROR');
+    assert.equal(json.error.message, 'device gone');
+    assert.equal(json.error.hint, 'check adb');
+    assert.equal(json.error.diagnosticId, err.diagnosticId);
+  });
+
+  it('toJSON omits hint when not provided', () => {
+    const err = new FlowWalkerError(ErrorCodes.COMMAND_FAILED, 'fail');
+    const json = err.toJSON();
+    assert.equal(json.error.hint, undefined);
+    assert.ok(!('hint' in json.error));
+  });
+
+  it('is instanceof Error', () => {
+    const err = new FlowWalkerError(ErrorCodes.INVALID_ARGS, 'x');
+    assert.ok(err instanceof Error);
+  });
+});
+
+describe('ErrorCodes', () => {
+  it('has all required codes', () => {
+    assert.ok(ErrorCodes.INVALID_ARGS);
+    assert.ok(ErrorCodes.INVALID_INPUT);
+    assert.ok(ErrorCodes.FILE_NOT_FOUND);
+    assert.ok(ErrorCodes.FLOW_PARSE_ERROR);
+    assert.ok(ErrorCodes.STEP_FAILED);
+    assert.ok(ErrorCodes.DEVICE_ERROR);
+    assert.ok(ErrorCodes.COMMAND_FAILED);
+  });
+});
+
+describe('formatError', () => {
+  it('formats FlowWalkerError as JSON', () => {
+    const err = new FlowWalkerError(ErrorCodes.INVALID_INPUT, 'bad', 'fix it');
+    const out = formatError(err, true);
+    const parsed = JSON.parse(out);
+    assert.equal(parsed.error.code, 'INVALID_INPUT');
+    assert.equal(parsed.error.message, 'bad');
+    assert.equal(parsed.error.hint, 'fix it');
+    assert.ok(parsed.error.diagnosticId);
+  });
+
+  it('formats FlowWalkerError as human text', () => {
+    const err = new FlowWalkerError(ErrorCodes.FILE_NOT_FOUND, 'missing', 'check path');
+    const out = formatError(err, false);
+    assert.ok(out.includes('FILE_NOT_FOUND'));
+    assert.ok(out.includes('missing'));
+    assert.ok(out.includes('Hint: check path'));
+    assert.ok(out.includes(err.diagnosticId));
+  });
+
+  it('wraps unknown errors with COMMAND_FAILED code', () => {
+    const out = formatError('something broke', true);
+    const parsed = JSON.parse(out);
+    assert.equal(parsed.error.code, 'COMMAND_FAILED');
+    assert.ok(parsed.error.message.includes('something broke'));
+    assert.ok(parsed.error.diagnosticId);
+  });
+
+  it('wraps Error objects with COMMAND_FAILED code', () => {
+    const out = formatError(new Error('native error'), true);
+    const parsed = JSON.parse(out);
+    assert.equal(parsed.error.code, 'COMMAND_FAILED');
+    assert.ok(parsed.error.message.includes('native error'));
+  });
+});

package/tests/fingerprint.test.ts

@@ -0,0 +1,85 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { computeFingerprint, deriveScreenName } from '../src/fingerprint.ts';
+import type { SnapshotElement } from '../src/types.ts';
+
+function el(type: string, text: string = '', flutterType?: string): SnapshotElement {
+  return { ref: '@e1', type, text, flutterType, enabled: true };
+}
+
+describe('computeFingerprint', () => {
+  it('returns deterministic hash for identical element sets', () => {
+    const elements = [el('button', 'Save'), el('button', 'Cancel'), el('textfield', 'Name')];
+    const hash1 = computeFingerprint(elements);
+    const hash2 = computeFingerprint(elements);
+    assert.equal(hash1, hash2, 'same elements should produce identical hash');
+  });
+
+  it('produces same hash regardless of element order', () => {
+    const a = [el('button', 'A'), el('textfield', 'B')];
+    const b = [el('textfield', 'B'), el('button', 'A')];
+    assert.equal(computeFingerprint(a), computeFingerprint(b));
+  });
+
+  it('ignores text content — same types with different text produce same hash', () => {
+    const a = [el('button', 'Save'), el('button', 'Next')];
+    const b = [el('button', 'Delete'), el('button', 'Back')];
+    assert.equal(computeFingerprint(a), computeFingerprint(b));
+  });
+
+  it('different element types produce different hashes', () => {
+    const a = [el('button', 'Go'), el('button', 'Stop')];
+    const b = [el('textfield', 'Name'), el('textfield', 'Email')];
+    assert.notEqual(computeFingerprint(a), computeFingerprint(b));
+  });
+
+  it('uses flutterType when available for fingerprinting', () => {
+    const withFlutter = [el('button', 'Go', 'ElevatedButton')];
+    const withoutFlutter = [el('button', 'Go')];
+    assert.notEqual(computeFingerprint(withFlutter), computeFingerprint(withoutFlutter));
+  });
+
+  it('bucketing: minor count differences produce same hash', () => {
+    // 2 buttons vs 3 buttons both bucket to 2
+    const two = [el('button', 'A'), el('button', 'B')];
+    const three = [el('button', 'A'), el('button', 'B'), el('button', 'C')];
+    assert.equal(computeFingerprint(two), computeFingerprint(three));
+  });
+
+  it('bucketing: large count differences produce different hash', () => {
+    // 1 button vs 8 buttons
+    const one = [el('button', 'A')];
+    const eight = Array.from({ length: 8 }, (_, i) => el('button', String(i)));
+    assert.notEqual(computeFingerprint(one), computeFingerprint(eight));
+  });
+
+  it('returns a 12-char hex string', () => {
+    const hash = computeFingerprint([el('button', 'X')]);
+    assert.match(hash, /^[0-9a-f]{12}$/);
+  });
+
+  it('handles empty element list', () => {
+    const hash = computeFingerprint([]);
+    assert.match(hash, /^[0-9a-f]{12}$/);
+  });
+});
+
+describe('deriveScreenName', () => {
+  it('uses first short text as screen name', () => {
+    const elements = [el('button', 'Settings'), el('button', 'Profile')];
+    const name = deriveScreenName(elements);
+    assert.equal(name, 'settings');
+  });
+
+  it('converts to kebab-case', () => {
+    const elements = [el('button', 'My Profile Page')];
+    const name = deriveScreenName(elements);
+    assert.equal(name, 'my-profile-page');
+  });
+
+  it('falls back to type-based name when no text', () => {
+    const elements = [el('button', ''), el('button', '')];
+    const name = deriveScreenName(elements);
+    assert.match(name, /^screen-button-2$/);
+  });
+});