flow-walker-cli 0.2.0

package/tests/flow-parser.test.ts

@@ -0,0 +1,264 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseFlow } from '../src/flow-parser.ts';
+
+describe('parseFlow', () => {
+  it('parses basic flow with name, description, setup', () => {
+    const yaml = `
+name: test-flow
+description: A test flow
+setup: normal
+
+steps:
+  - name: First step
+    screenshot: step1
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.name, 'test-flow');
+    assert.equal(flow.description, 'A test flow');
+    assert.equal(flow.setup, 'normal');
+    assert.equal(flow.steps.length, 1);
+  });
+
+  it('parses covers and prerequisites arrays', () => {
+    const yaml = `
+name: with-meta
+description: Flow with metadata
+covers:
+  - app/lib/pages/home.dart
+  - app/lib/pages/settings.dart
+prerequisites:
+  - auth_ready
+setup: normal
+
+steps:
+  - name: Step one
+    screenshot: s1
+`;
+    const flow = parseFlow(yaml);
+    assert.deepEqual(flow.covers, ['app/lib/pages/home.dart', 'app/lib/pages/settings.dart']);
+    assert.deepEqual(flow.prerequisites, ['auth_ready']);
+  });
+
+  it('parses press step with inline object', () => {
+    const yaml = `
+name: press-test
+description: Test press parsing
+steps:
+  - name: Press button
+    press: { type: button, position: rightmost }
+    screenshot: pressed
+`;
+    const flow = parseFlow(yaml);
+    const step = flow.steps[0];
+    assert.deepEqual(step.press, { type: 'button', position: 'rightmost' });
+    assert.equal(step.screenshot, 'pressed');
+  });
+
+  it('parses press with bottom_nav_tab as number', () => {
+    const yaml = `
+name: nav-test
+description: Nav tab test
+steps:
+  - name: Go to tab 2
+    press: { bottom_nav_tab: 2 }
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.steps[0].press?.bottom_nav_tab, 2);
+  });
+
+  it('parses scroll step', () => {
+    const yaml = `
+name: scroll-test
+description: Scroll test
+steps:
+  - name: Scroll down
+    scroll: down
+    screenshot: scrolled
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.steps[0].scroll, 'down');
+  });
+
+  it('parses fill step', () => {
+    const yaml = `
+name: fill-test
+description: Fill test
+steps:
+  - name: Fill text
+    fill: { type: textfield, value: "Hello world" }
+    screenshot: filled
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.steps[0].fill?.type, 'textfield');
+    assert.equal(flow.steps[0].fill?.value, 'Hello world');
+  });
+
+  it('parses back step', () => {
+    const yaml = `
+name: back-test
+description: Back test
+steps:
+  - name: Go back
+    back: true
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.steps[0].back, true);
+  });
+
+  it('parses assert with interactive_count', () => {
+    const yaml = `
+name: assert-test
+description: Assert test
+steps:
+  - name: Check elements
+    assert:
+      interactive_count: { min: 20 }
+    screenshot: home
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.steps[0].assert?.interactive_count?.min, 20);
+  });
+
+  it('parses assert with bottom_nav_tabs', () => {
+    const yaml = `
+name: nav-assert
+description: Nav tabs assert
+steps:
+  - name: Check nav
+    assert:
+      bottom_nav_tabs: { min: 4 }
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.steps[0].assert?.bottom_nav_tabs?.min, 4);
+  });
+
+  it('parses assert with has_type', () => {
+    const yaml = `
+name: type-assert
+description: Type assert
+steps:
+  - name: Check switches
+    assert:
+      has_type: { type: switch, min: 2 }
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.steps[0].assert?.has_type?.type, 'switch');
+    assert.equal(flow.steps[0].assert?.has_type?.min, 2);
+  });
+
+  it('parses note field (ignored by executor)', () => {
+    const yaml = `
+name: note-test
+description: Note test
+steps:
+  - name: Step with note
+    note: "This is a human-readable note"
+    screenshot: noted
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.steps[0].note, 'This is a human-readable note');
+  });
+
+  it('parses multiple steps in order', () => {
+    const yaml = `
+name: multi-step
+description: Multiple steps
+steps:
+  - name: Step 1
+    screenshot: s1
+  - name: Step 2
+    press: { type: button }
+  - name: Step 3
+    back: true
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.steps.length, 3);
+    assert.equal(flow.steps[0].name, 'Step 1');
+    assert.equal(flow.steps[1].name, 'Step 2');
+    assert.equal(flow.steps[2].name, 'Step 3');
+  });
+
+  it('strips inline YAML comments', () => {
+    const yaml = `
+name: comment-test
+description: Test with comments
+prerequisites:
+  - auth_ready  # User must be signed in
+setup: normal
+
+steps:
+  - name: Check home
+    screenshot: home
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.prerequisites![0], 'auth_ready');
+  });
+
+  it('throws on missing name', () => {
+    const yaml = `
+description: No name
+steps:
+  - name: Step 1
+`;
+    assert.throws(() => parseFlow(yaml), /missing required field: name/i);
+  });
+
+  it('throws on empty steps', () => {
+    const yaml = `
+name: empty
+description: Empty steps
+steps:
+`;
+    assert.throws(() => parseFlow(yaml), /no steps/i);
+  });
+
+  it('parses real-world flow format (home-navigation style)', () => {
+    const yaml = `# E2E Flow: Home screen navigation
+# Tests: snapshot, settings button, scroll, back navigation
+
+name: home-navigation
+description: Home screen snapshot, settings gear press, scroll in settings, back to home
+covers:
+  - app/lib/pages/home/page.dart
+  - app/lib/pages/settings/settings_drawer.dart
+prerequisites:
+  - auth_ready  # User completed real sign-in
+setup: normal
+
+steps:
+  - name: Snapshot home screen
+    assert:
+      interactive_count: { min: 20, verified: "flow-walker run10: 24 elements" }
+    screenshot: home
+
+  - name: Press settings gear (rightmost button in top bar)
+    press: { type: button, position: rightmost }
+    assert:
+      interactive_count: { min: 10 }
+    screenshot: settings
+
+  - name: Scroll down in settings
+    scroll: down
+    screenshot: settings-scrolled
+
+  - name: Back to home
+    back: true
+    assert:
+      interactive_count: { min: 5 }
+    screenshot: final
+`;
+    const flow = parseFlow(yaml);
+    assert.equal(flow.name, 'home-navigation');
+    assert.equal(flow.steps.length, 4);
+    assert.equal(flow.steps[0].assert?.interactive_count?.min, 20);
+    assert.equal(flow.steps[1].press?.type, 'button');
+    assert.equal(flow.steps[1].press?.position, 'rightmost');
+    assert.equal(flow.steps[2].scroll, 'down');
+    assert.equal(flow.steps[3].back, true);
+    assert.deepEqual(flow.covers, [
+      'app/lib/pages/home/page.dart',
+      'app/lib/pages/settings/settings_drawer.dart'
+    ]);
+  });
+});

package/tests/graph.test.ts

@@ -0,0 +1,111 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { NavigationGraph } from '../src/graph.ts';
+
+describe('NavigationGraph', () => {
+  it('adds screens and tracks visit count', () => {
+    const g = new NavigationGraph();
+    g.addScreen('abc123', 'home', ['button', 'textfield'], 5);
+    assert.equal(g.screenCount(), 1);
+    assert.equal(g.visitCount('abc123'), 1);
+
+    g.addScreen('abc123', 'home', ['button', 'textfield'], 5);
+    assert.equal(g.screenCount(), 1);
+    assert.equal(g.visitCount('abc123'), 2);
+  });
+
+  it('hasScreen returns correct state', () => {
+    const g = new NavigationGraph();
+    assert.equal(g.hasScreen('abc'), false);
+    g.addScreen('abc', 'home', [], 0);
+    assert.equal(g.hasScreen('abc'), true);
+  });
+
+  it('adds edges between screens', () => {
+    const g = new NavigationGraph();
+    g.addScreen('a', 'home', [], 3);
+    g.addScreen('b', 'settings', [], 5);
+    g.addEdge('a', 'b', { ref: '@e1', type: 'button', text: 'Settings' });
+
+    assert.equal(g.edges.length, 1);
+    assert.equal(g.edges[0].source, 'a');
+    assert.equal(g.edges[0].target, 'b');
+  });
+
+  it('deduplicates identical edges', () => {
+    const g = new NavigationGraph();
+    g.addScreen('a', 'home', [], 3);
+    g.addScreen('b', 'settings', [], 5);
+
+    const el = { ref: '@e1', type: 'button', text: 'Settings' };
+    g.addEdge('a', 'b', el);
+    g.addEdge('a', 'b', el); // duplicate
+    assert.equal(g.edges.length, 1);
+  });
+
+  it('allows different edges between same screens', () => {
+    const g = new NavigationGraph();
+    g.addScreen('a', 'home', [], 3);
+    g.addScreen('b', 'settings', [], 5);
+
+    g.addEdge('a', 'b', { ref: '@e1', type: 'button', text: 'Settings' });
+    g.addEdge('a', 'b', { ref: '@e2', type: 'gesture', text: 'Gear icon' });
+    assert.equal(g.edges.length, 2);
+  });
+
+  it('edgesFrom returns correct edges', () => {
+    const g = new NavigationGraph();
+    g.addScreen('a', 'home', [], 3);
+    g.addScreen('b', 'settings', [], 5);
+    g.addScreen('c', 'profile', [], 4);
+
+    g.addEdge('a', 'b', { ref: '@e1', type: 'button', text: 'Settings' });
+    g.addEdge('a', 'c', { ref: '@e2', type: 'button', text: 'Profile' });
+    g.addEdge('b', 'c', { ref: '@e3', type: 'button', text: 'Profile' });
+
+    assert.equal(g.edgesFrom('a').length, 2);
+    assert.equal(g.edgesFrom('b').length, 1);
+    assert.equal(g.edgesFrom('c').length, 0);
+  });
+
+  it('edgesTo returns correct edges', () => {
+    const g = new NavigationGraph();
+    g.addScreen('a', 'home', [], 3);
+    g.addScreen('b', 'settings', [], 5);
+
+    g.addEdge('a', 'b', { ref: '@e1', type: 'button', text: 'Settings' });
+    assert.equal(g.edgesTo('b').length, 1);
+    assert.equal(g.edgesTo('a').length, 0);
+  });
+
+  it('cycle detection: hasScreen prevents revisiting', () => {
+    const g = new NavigationGraph();
+    g.addScreen('a', 'home', [], 3);
+    g.addScreen('b', 'settings', [], 5);
+    g.addEdge('a', 'b', { ref: '@e1', type: 'button', text: 'Settings' });
+
+    // Simulate cycle: b → a
+    g.addEdge('b', 'a', { ref: '@e2', type: 'button', text: 'Back' });
+
+    // Walker would check hasScreen before recursing
+    assert.equal(g.hasScreen('a'), true);
+    assert.equal(g.visitCount('a'), 1);
+    // visitCount > 1 would trigger cycle skip in walker
+  });
+
+  it('toJSON produces serializable output', () => {
+    const g = new NavigationGraph();
+    g.addScreen('a', 'home', ['button'], 3);
+    g.addScreen('b', 'settings', ['button', 'switch'], 5);
+    g.addEdge('a', 'b', { ref: '@e1', type: 'button', text: 'Settings' });
+
+    const json = g.toJSON();
+    assert.equal(json.nodes.length, 2);
+    assert.equal(json.edges.length, 1);
+
+    // Verify it's JSON-serializable
+    const str = JSON.stringify(json);
+    const parsed = JSON.parse(str);
+    assert.equal(parsed.nodes.length, 2);
+  });
+});

package/tests/reporter.test.ts

@@ -0,0 +1,188 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildHtml } from '../src/reporter.ts';
+import type { RunResult } from '../src/run-schema.ts';
+
+const makeRun = (overrides: Partial<RunResult> = {}): RunResult => ({
+  id: 'test_runId1',
+  flow: 'tab-navigation',
+  device: 'Pixel_7a',
+  startedAt: '2026-03-12T10:00:00Z',
+  duration: 17600,
+  result: 'pass',
+  steps: [
+    {
+      index: 0,
+      name: 'Verify home tab',
+      action: 'assert',
+      status: 'pass',
+      timestamp: 1000,
+      duration: 2300,
+      elementCount: 24,
+      screenshot: 'step-1-home.png',
+      assertion: { interactive_count: { min: 20, actual: 24 } },
+    },
+    {
+      index: 1,
+      name: 'Press settings',
+      action: 'press',
+      status: 'pass',
+      timestamp: 3300,
+      duration: 1500,
+      elementCount: 18,
+    },
+  ],
+  ...overrides,
+});
+
+describe('buildHtml', () => {
+  it('returns valid HTML document', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.startsWith('<!DOCTYPE html>'));
+    assert.ok(html.includes('</html>'));
+  });
+
+  it('includes flow name in title and header', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes('<title>E2E Flow Viewer: tab-navigation</title>'));
+    assert.ok(html.includes('tab-navigation'));
+  });
+
+  it('includes device name and duration in meta', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes('Pixel_7a'));
+    assert.ok(html.includes('17.6s'));
+  });
+
+  it('renders pass/fail counts in legend', () => {
+    const run = makeRun({
+      result: 'fail',
+      steps: [
+        { index: 0, name: 'S1', action: 'assert', status: 'pass', timestamp: 0, duration: 100, elementCount: 5 },
+        { index: 1, name: 'S2', action: 'press', status: 'fail', timestamp: 100, duration: 200, elementCount: 3, error: 'not found' },
+      ],
+    });
+    const html = buildHtml(run, '', new Map());
+    assert.ok(html.includes('PASS (1)'));
+    assert.ok(html.includes('FAIL (1)'));
+    assert.ok(html.includes('1 FAIL'));
+  });
+
+  it('embeds video when base64 provided', () => {
+    const videoB64 = 'AAAA'; // dummy base64
+    const html = buildHtml(makeRun(), videoB64, new Map());
+    assert.ok(html.includes('<video id="video"'));
+    assert.ok(html.includes('data:video/mp4;base64,AAAA'));
+    assert.ok(!html.includes('No video'));
+  });
+
+  it('shows no-video placeholder when no base64', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes('No video'));
+    assert.ok(!html.includes('data:video/mp4'));
+  });
+
+  it('renders step cards with data-time for seek', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    // Step 1 timestamp 1000ms → 1.0 sec
+    assert.ok(html.includes('data-time="1.0"'));
+    // Step 2 timestamp 3300ms → 3.3 sec
+    assert.ok(html.includes('data-time="3.3"'));
+  });
+
+  it('renders step cards with jumpTo onclick', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes('onclick="jumpTo('));
+  });
+
+  it('includes step names', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes('Verify home tab'));
+    assert.ok(html.includes('Press settings'));
+  });
+
+  it('renders pass/fail status classes on steps', () => {
+    const run = makeRun({
+      steps: [
+        { index: 0, name: 'Good', action: 'assert', status: 'pass', timestamp: 0, duration: 100, elementCount: 5 },
+        { index: 1, name: 'Bad', action: 'press', status: 'fail', timestamp: 100, duration: 200, elementCount: 0, error: 'fail' },
+      ],
+    });
+    const html = buildHtml(run, '', new Map());
+    assert.ok(html.includes('class="step pass"'));
+    assert.ok(html.includes('class="step fail"'));
+  });
+
+  it('embeds screenshot thumbnails as base64 images', () => {
+    const screenshots = new Map([['step-1-home.png', 'iVBOR']]);
+    const html = buildHtml(makeRun(), '', screenshots);
+    assert.ok(html.includes('data:image/png;base64,iVBOR'));
+    assert.ok(html.includes('class="step-thumb"'));
+  });
+
+  it('renders assertion results in step detail', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes('24 elements'));
+  });
+
+  it('renders error messages for failed steps', () => {
+    const run = makeRun({
+      steps: [
+        { index: 0, name: 'Broken', action: 'press', status: 'fail', timestamp: 0, duration: 100, elementCount: 0, error: 'element not found' },
+      ],
+    });
+    const html = buildHtml(run, '', new Map());
+    assert.ok(html.includes('element not found'));
+  });
+
+  it('includes keyboard shortcut script', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes("document.addEventListener('keydown'"));
+    assert.ok(html.includes('video.paused'));
+  });
+
+  it('includes timeupdate listener for auto-highlight', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes("video.addEventListener('timeupdate'"));
+  });
+
+  it('escapes HTML special characters in flow name', () => {
+    const run = makeRun({ flow: '<script>alert("xss")</script>' });
+    const html = buildHtml(run, '', new Map());
+    assert.ok(!html.includes('<script>alert'));
+    assert.ok(html.includes('&lt;script&gt;'));
+  });
+
+  it('renders step numbers starting from 1', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes('>1</div>'));
+    assert.ok(html.includes('>2</div>'));
+  });
+
+  it('includes responsive CSS media query', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes('@media (max-width: 768px)'));
+  });
+
+  it('renders all-pass summary when all steps pass', () => {
+    const html = buildHtml(makeRun(), '', new Map());
+    assert.ok(html.includes('All PASS'));
+  });
+
+  it('renders bottom_nav_tabs assertion result', () => {
+    const run = makeRun({
+      steps: [{
+        index: 0,
+        name: 'Check nav',
+        action: 'assert',
+        status: 'pass',
+        timestamp: 0,
+        duration: 100,
+        elementCount: 20,
+        assertion: { bottom_nav_tabs: { min: 4, actual: 5 } },
+      }],
+    });
+    const html = buildHtml(run, '', new Map());
+    assert.ok(html.includes('5 nav tabs'));
+  });
+});

package/tests/run-schema.test.ts

@@ -0,0 +1,138 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateRunResult, generateRunId } from '../src/run-schema.ts';
+import type { RunResult } from '../src/run-schema.ts';
+
+describe('validateRunResult', () => {
+  const validRun: RunResult = {
+    id: 'P-tnB_sgKA',
+    flow: 'tab-navigation',
+    device: 'Pixel_7a',
+    startedAt: '2026-03-12T10:00:00Z',
+    duration: 17600,
+    result: 'pass',
+    steps: [
+      {
+        index: 0,
+        name: 'Verify home tab',
+        action: 'assert',
+        status: 'pass',
+        timestamp: 1000,
+        duration: 2300,
+        elementCount: 24,
+        screenshot: 'step-1-home.png',
+        assertion: { interactive_count: { min: 20, actual: 24 } },
+      },
+    ],
+    video: 'recording.mp4',
+    log: 'device.log',
+  };
+
+  it('accepts valid run result', () => {
+    assert.equal(validateRunResult(validRun), true);
+  });
+
+  it('accepts run with fail status', () => {
+    const failRun = { ...validRun, result: 'fail' as const };
+    assert.equal(validateRunResult(failRun), true);
+  });
+
+  it('accepts run without video and log', () => {
+    const { video, log, ...minimal } = validRun;
+    assert.equal(validateRunResult(minimal), true);
+  });
+
+  it('accepts step with fail status', () => {
+    const run = {
+      ...validRun,
+      steps: [{ ...validRun.steps[0], status: 'fail' as const, error: 'element not found' }],
+    };
+    assert.equal(validateRunResult(run), true);
+  });
+
+  it('accepts step with skip status', () => {
+    const run = {
+      ...validRun,
+      steps: [{ ...validRun.steps[0], status: 'skip' as const }],
+    };
+    assert.equal(validateRunResult(run), true);
+  });
+
+  it('rejects null', () => {
+    assert.equal(validateRunResult(null), false);
+  });
+
+  it('rejects non-object', () => {
+    assert.equal(validateRunResult('string'), false);
+  });
+
+  it('rejects missing id field', () => {
+    const { id, ...noId } = validRun;
+    assert.equal(validateRunResult(noId), false);
+  });
+
+  it('rejects missing flow field', () => {
+    const { flow, ...noFlow } = validRun;
+    assert.equal(validateRunResult(noFlow), false);
+  });
+
+  it('rejects missing device field', () => {
+    const { device, ...noDevice } = validRun;
+    assert.equal(validateRunResult(noDevice), false);
+  });
+
+  it('rejects invalid result value', () => {
+    assert.equal(validateRunResult({ ...validRun, result: 'unknown' }), false);
+  });
+
+  it('rejects non-array steps', () => {
+    assert.equal(validateRunResult({ ...validRun, steps: 'not-array' }), false);
+  });
+
+  it('rejects step missing name', () => {
+    const { name, ...noName } = validRun.steps[0];
+    assert.equal(validateRunResult({ ...validRun, steps: [noName] }), false);
+  });
+
+  it('rejects step missing action', () => {
+    const { action, ...noAction } = validRun.steps[0];
+    assert.equal(validateRunResult({ ...validRun, steps: [noAction] }), false);
+  });
+
+  it('rejects step with invalid status', () => {
+    const badStep = { ...validRun.steps[0], status: 'maybe' };
+    assert.equal(validateRunResult({ ...validRun, steps: [badStep] }), false);
+  });
+
+  it('rejects step missing timestamp', () => {
+    const { timestamp, ...noTs } = validRun.steps[0];
+    assert.equal(validateRunResult({ ...validRun, steps: [noTs] }), false);
+  });
+
+  it('rejects step missing duration', () => {
+    const { duration, ...noDur } = validRun.steps[0];
+    assert.equal(validateRunResult({ ...validRun, steps: [noDur] }), false);
+  });
+
+  it('rejects step missing elementCount', () => {
+    const { elementCount, ...noCount } = validRun.steps[0];
+    assert.equal(validateRunResult({ ...validRun, steps: [noCount] }), false);
+  });
+});
+
+describe('generateRunId', () => {
+  it('returns a 10-character string', () => {
+    const id = generateRunId();
+    assert.equal(id.length, 10);
+  });
+
+  it('is URL-safe (base64url charset)', () => {
+    const id = generateRunId();
+    assert.match(id, /^[A-Za-z0-9_-]+$/);
+  });
+
+  it('generates unique IDs', () => {
+    const ids = new Set(Array.from({ length: 100 }, () => generateRunId()));
+    assert.equal(ids.size, 100);
+  });
+});