flow-walker-cli 0.2.0

package/tests/runner.test.ts

@@ -0,0 +1,150 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolvePress, resolveFill, getStepAction } from '../src/runner.ts';
+import type { SnapshotElement, FlowStep } from '../src/types.ts';
+
+const makeElement = (overrides: Partial<SnapshotElement> = {}): SnapshotElement => ({
+  ref: '@e1',
+  type: 'button',
+  text: 'OK',
+  enabled: true,
+  bounds: { x: 100, y: 200, width: 80, height: 40 },
+  ...overrides,
+});
+
+describe('getStepAction', () => {
+  it('returns "press" for press step', () => {
+    assert.equal(getStepAction({ name: 'x', press: { type: 'button' } }), 'press');
+  });
+
+  it('returns "scroll" for scroll step', () => {
+    assert.equal(getStepAction({ name: 'x', scroll: 'down' }), 'scroll');
+  });
+
+  it('returns "fill" for fill step', () => {
+    assert.equal(getStepAction({ name: 'x', fill: { value: 'hello' } }), 'fill');
+  });
+
+  it('returns "back" for back step', () => {
+    assert.equal(getStepAction({ name: 'x', back: true }), 'back');
+  });
+
+  it('returns "assert" for assert step', () => {
+    assert.equal(getStepAction({ name: 'x', assert: { interactive_count: { min: 5 } } }), 'assert');
+  });
+
+  it('returns "screenshot" for screenshot-only step', () => {
+    assert.equal(getStepAction({ name: 'x', screenshot: 'home' }), 'screenshot');
+  });
+
+  it('returns "unknown" for empty step', () => {
+    assert.equal(getStepAction({ name: 'x' }), 'unknown');
+  });
+});
+
+describe('resolvePress', () => {
+  it('resolves by ref', () => {
+    const els = [makeElement({ ref: '@e1' }), makeElement({ ref: '@e2' })];
+    const result = resolvePress({ ref: '@e2' }, els);
+    assert.equal(result?.ref, '@e2');
+  });
+
+  it('returns null for missing ref', () => {
+    const els = [makeElement({ ref: '@e1' })];
+    const result = resolvePress({ ref: '@e99' }, els);
+    assert.equal(result, null);
+  });
+
+  it('resolves by bottom_nav_tab index', () => {
+    const els = [
+      makeElement({ ref: '@nav0', flutterType: 'InkWell', bounds: { x: 10, y: 800, width: 80, height: 50 } }),
+      makeElement({ ref: '@nav1', flutterType: 'InkWell', bounds: { x: 100, y: 800, width: 80, height: 50 } }),
+      makeElement({ ref: '@nav2', flutterType: 'InkWell', bounds: { x: 200, y: 800, width: 80, height: 50 } }),
+    ];
+    const result = resolvePress({ bottom_nav_tab: 1 }, els);
+    assert.equal(result?.ref, '@nav1');
+  });
+
+  it('returns null for out-of-range bottom_nav_tab', () => {
+    const els = [
+      makeElement({ ref: '@nav0', flutterType: 'InkWell', bounds: { x: 10, y: 800, width: 80, height: 50 } }),
+    ];
+    const result = resolvePress({ bottom_nav_tab: 5 }, els);
+    assert.equal(result, null);
+  });
+
+  it('resolves by type', () => {
+    const els = [
+      makeElement({ ref: '@e1', type: 'textfield' }),
+      makeElement({ ref: '@e2', type: 'button' }),
+    ];
+    const result = resolvePress({ type: 'button' }, els);
+    assert.equal(result?.ref, '@e2');
+  });
+
+  it('resolves by type with rightmost position', () => {
+    const els = [
+      makeElement({ ref: '@e1', type: 'button', bounds: { x: 10, y: 100, width: 40, height: 40 } }),
+      makeElement({ ref: '@e2', type: 'button', bounds: { x: 300, y: 100, width: 40, height: 40 } }),
+      makeElement({ ref: '@e3', type: 'button', bounds: { x: 150, y: 100, width: 40, height: 40 } }),
+    ];
+    const result = resolvePress({ type: 'button', position: 'rightmost' }, els);
+    assert.equal(result?.ref, '@e2');
+  });
+
+  it('resolves by type with leftmost position', () => {
+    const els = [
+      makeElement({ ref: '@e1', type: 'button', bounds: { x: 300, y: 100, width: 40, height: 40 } }),
+      makeElement({ ref: '@e2', type: 'button', bounds: { x: 10, y: 100, width: 40, height: 40 } }),
+    ];
+    const result = resolvePress({ type: 'button', position: 'leftmost' }, els);
+    assert.equal(result?.ref, '@e2');
+  });
+
+  it('resolves by flutterType partial match', () => {
+    const els = [
+      makeElement({ ref: '@e1', type: 'gesture', flutterType: 'ElevatedButton' }),
+    ];
+    const result = resolvePress({ type: 'elevatedbutton' }, els);
+    assert.equal(result?.ref, '@e1');
+  });
+
+  it('returns null when no match', () => {
+    const els = [makeElement({ ref: '@e1', type: 'textfield' })];
+    const result = resolvePress({ type: 'switch' }, els);
+    assert.equal(result, null);
+  });
+
+  it('returns null for empty press config', () => {
+    const els = [makeElement()];
+    const result = resolvePress({}, els);
+    assert.equal(result, null);
+  });
+});
+
+describe('resolveFill', () => {
+  it('resolves textfield by type', () => {
+    const els = [
+      makeElement({ ref: '@e1', type: 'button' }),
+      makeElement({ ref: '@e2', type: 'textfield' }),
+    ];
+    const result = resolveFill({ type: 'textfield', value: 'hi' }, els);
+    assert.equal(result?.ref, '@e2');
+  });
+
+  it('resolves TextField by flutterType when no type match', () => {
+    const els = [
+      makeElement({ ref: '@e1', type: 'gesture', flutterType: 'TextField' }),
+    ];
+    const result = resolveFill({ value: 'hello' }, els);
+    assert.equal(result?.ref, '@e1');
+  });
+
+  it('returns null when no textfield available', () => {
+    const els = [
+      makeElement({ ref: '@e1', type: 'button' }),
+    ];
+    const result = resolveFill({ value: 'hi' }, els);
+    assert.equal(result, null);
+  });
+});

package/tests/safety.test.ts

@@ -0,0 +1,115 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { isSafe, filterSafe } from '../src/safety.ts';
+import type { SnapshotElement } from '../src/types.ts';
+
+function el(ref: string, type: string, text: string, opts?: Partial<SnapshotElement>): SnapshotElement {
+  return { ref, type, text, enabled: true, ...opts };
+}
+
+describe('isSafe', () => {
+  it('returns safe for normal button', () => {
+    const element = el('@e1', 'button', 'Save');
+    const result = isSafe(element, []);
+    assert.equal(result.safe, true);
+  });
+
+  it('blocks element with "delete" in text', () => {
+    const element = el('@e1', 'button', 'Delete Account');
+    const result = isSafe(element, []);
+    assert.equal(result.safe, false);
+    assert.ok(result.reason?.includes('delete'));
+  });
+
+  it('blocks element with "sign out" in text', () => {
+    const element = el('@e1', 'button', 'Sign Out');
+    const result = isSafe(element, []);
+    assert.equal(result.safe, false);
+    assert.ok(result.reason?.includes('sign out'));
+  });
+
+  it('blocks element with "remove" in text', () => {
+    const element = el('@e1', 'button', 'Remove Device');
+    const result = isSafe(element, []);
+    assert.equal(result.safe, false);
+  });
+
+  it('blocks element with "reset" in text', () => {
+    const element = el('@e1', 'button', 'Reset All Settings');
+    const result = isSafe(element, []);
+    assert.equal(result.safe, false);
+  });
+
+  it('blocks element with "unpair" in text', () => {
+    const element = el('@e1', 'button', 'Unpair Device');
+    const result = isSafe(element, []);
+    assert.equal(result.safe, false);
+  });
+
+  it('blocks element with "logout" in text', () => {
+    const element = el('@e1', 'button', 'Logout');
+    const result = isSafe(element, []);
+    assert.equal(result.safe, false);
+  });
+
+  it('blocks disabled elements', () => {
+    const element = el('@e1', 'button', 'Save', { enabled: false });
+    const result = isSafe(element, []);
+    assert.equal(result.safe, false);
+    assert.ok(result.reason?.includes('disabled'));
+  });
+
+  it('is case-insensitive on blocklist matching', () => {
+    const element = el('@e1', 'button', 'DELETE');
+    const result = isSafe(element, []);
+    assert.equal(result.safe, false);
+  });
+
+  it('blocks based on nearby element text', () => {
+    const target = el('@e1', 'button', 'Confirm', { bounds: { x: 100, y: 200, width: 80, height: 40 } });
+    const nearby = el('@e2', 'label', 'Delete Account', { bounds: { x: 100, y: 180, width: 200, height: 20 } });
+    const result = isSafe(target, [target, nearby]);
+    assert.equal(result.safe, false);
+    assert.ok(result.reason?.includes('nearby'));
+  });
+
+  it('allows custom blocklist', () => {
+    const element = el('@e1', 'button', 'Explode');
+    const result = isSafe(element, [], ['explode']);
+    assert.equal(result.safe, false);
+  });
+
+  it('does not block when custom blocklist is empty', () => {
+    const element = el('@e1', 'button', 'Delete');
+    const result = isSafe(element, [], []);
+    assert.equal(result.safe, true);
+  });
+});
+
+describe('filterSafe', () => {
+  it('separates safe and unsafe elements', () => {
+    const elements = [
+      el('@e1', 'button', 'Save'),
+      el('@e2', 'button', 'Delete'),
+      el('@e3', 'button', 'Cancel'),
+      el('@e4', 'button', 'Sign Out'),
+    ];
+
+    const [safe, skipped] = filterSafe(elements);
+    assert.equal(safe.length, 2);
+    assert.equal(skipped.length, 2);
+    assert.deepEqual(safe.map(e => e.text), ['Save', 'Cancel']);
+    assert.deepEqual(skipped.map(s => s.element.text), ['Delete', 'Sign Out']);
+  });
+
+  it('returns all elements as safe when none match blocklist', () => {
+    const elements = [
+      el('@e1', 'button', 'Save'),
+      el('@e2', 'button', 'Next'),
+    ];
+
+    const [safe, skipped] = filterSafe(elements);
+    assert.equal(safe.length, 2);
+    assert.equal(skipped.length, 0);
+  });
+});

package/tests/validate.test.ts

@@ -0,0 +1,193 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { writeFileSync, unlinkSync, mkdirSync, rmdirSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  rejectControlChars,
+  validateFlowPath,
+  validateOutputDir,
+  validateUri,
+  validateBundleId,
+  validateRunDir,
+} from '../src/validate.ts';
+import { FlowWalkerError } from '../src/errors.ts';
+
+const tmpDir = join(import.meta.dirname!, '..', '.test-tmp-validate');
+
+describe('rejectControlChars', () => {
+  it('accepts normal strings', () => {
+    assert.doesNotThrow(() => rejectControlChars('hello world', 'test'));
+  });
+
+  it('accepts newlines and tabs', () => {
+    assert.doesNotThrow(() => rejectControlChars('line1\nline2\ttab', 'test'));
+  });
+
+  it('rejects null byte', () => {
+    assert.throws(() => rejectControlChars('bad\x00input', 'test'), FlowWalkerError);
+  });
+
+  it('rejects bell character', () => {
+    assert.throws(() => rejectControlChars('bad\x07input', 'test'), FlowWalkerError);
+  });
+
+  it('rejects backspace', () => {
+    assert.throws(() => rejectControlChars('bad\x08input', 'test'), FlowWalkerError);
+  });
+
+  it('error has INVALID_INPUT code', () => {
+    try {
+      rejectControlChars('bad\x00input', 'Path');
+      assert.fail('should throw');
+    } catch (err) {
+      assert.ok(err instanceof FlowWalkerError);
+      assert.equal(err.code, 'INVALID_INPUT');
+      assert.ok(err.message.includes('Path'));
+    }
+  });
+});
+
+describe('validateFlowPath', () => {
+  it('accepts valid .yaml file', () => {
+    mkdirSync(tmpDir, { recursive: true });
+    const p = join(tmpDir, 'test.yaml');
+    writeFileSync(p, 'name: test\nsteps:\n  - name: s1\n');
+    assert.doesNotThrow(() => validateFlowPath(p));
+    unlinkSync(p);
+    rmdirSync(tmpDir);
+  });
+
+  it('accepts valid .yml file', () => {
+    mkdirSync(tmpDir, { recursive: true });
+    const p = join(tmpDir, 'test.yml');
+    writeFileSync(p, 'name: test\nsteps:\n  - name: s1\n');
+    assert.doesNotThrow(() => validateFlowPath(p));
+    unlinkSync(p);
+    rmdirSync(tmpDir);
+  });
+
+  it('rejects non-yaml extension', () => {
+    assert.throws(() => validateFlowPath('/tmp/test.json'), FlowWalkerError);
+  });
+
+  it('rejects path traversal', () => {
+    assert.throws(() => validateFlowPath('../../../etc/passwd.yaml'), FlowWalkerError);
+  });
+
+  it('rejects nonexistent file', () => {
+    try {
+      validateFlowPath('/tmp/definitely-not-here-xyz.yaml');
+      assert.fail('should throw');
+    } catch (err) {
+      assert.ok(err instanceof FlowWalkerError);
+      assert.equal(err.code, 'FILE_NOT_FOUND');
+    }
+  });
+
+  it('rejects control characters', () => {
+    assert.throws(() => validateFlowPath('/tmp/bad\x00.yaml'), FlowWalkerError);
+  });
+});
+
+describe('validateOutputDir', () => {
+  it('accepts normal paths', () => {
+    assert.doesNotThrow(() => validateOutputDir('./output'));
+    assert.doesNotThrow(() => validateOutputDir('/tmp/results'));
+  });
+
+  it('rejects path traversal', () => {
+    assert.throws(() => validateOutputDir('../../etc'), FlowWalkerError);
+  });
+
+  it('rejects control characters', () => {
+    assert.throws(() => validateOutputDir('/tmp/bad\x00dir'), FlowWalkerError);
+  });
+});
+
+describe('validateUri', () => {
+  it('accepts valid ws:// URI', () => {
+    assert.doesNotThrow(() => validateUri('ws://127.0.0.1:38047/abc=/ws'));
+  });
+
+  it('accepts valid wss:// URI', () => {
+    assert.doesNotThrow(() => validateUri('wss://secure.host:443/path'));
+  });
+
+  it('rejects http:// URI', () => {
+    assert.throws(() => validateUri('http://127.0.0.1:38047'), FlowWalkerError);
+  });
+
+  it('rejects empty string', () => {
+    assert.throws(() => validateUri(''), FlowWalkerError);
+  });
+
+  it('rejects control characters', () => {
+    assert.throws(() => validateUri('ws://bad\x00host'), FlowWalkerError);
+  });
+
+  it('error has hint with example', () => {
+    try {
+      validateUri('http://wrong');
+      assert.fail('should throw');
+    } catch (err) {
+      assert.ok(err instanceof FlowWalkerError);
+      assert.ok(err.hint?.includes('ws://'));
+    }
+  });
+});
+
+describe('validateBundleId', () => {
+  it('accepts valid reverse-domain ID', () => {
+    assert.doesNotThrow(() => validateBundleId('com.example.app'));
+    assert.doesNotThrow(() => validateBundleId('com.friend.ios.dev'));
+  });
+
+  it('rejects single-segment ID', () => {
+    assert.throws(() => validateBundleId('myapp'), FlowWalkerError);
+  });
+
+  it('rejects control characters', () => {
+    assert.throws(() => validateBundleId('com.bad\x00.app'), FlowWalkerError);
+  });
+
+  it('rejects starting with number', () => {
+    assert.throws(() => validateBundleId('123.example.app'), FlowWalkerError);
+  });
+});
+
+describe('validateRunDir', () => {
+  it('accepts directory with run.json', () => {
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, 'run.json'), '{}');
+    assert.doesNotThrow(() => validateRunDir(tmpDir));
+    unlinkSync(join(tmpDir, 'run.json'));
+    rmdirSync(tmpDir);
+  });
+
+  it('rejects nonexistent directory', () => {
+    try {
+      validateRunDir('/tmp/no-such-dir-xyz');
+      assert.fail('should throw');
+    } catch (err) {
+      assert.ok(err instanceof FlowWalkerError);
+      assert.equal(err.code, 'FILE_NOT_FOUND');
+    }
+  });
+
+  it('rejects directory without run.json', () => {
+    mkdirSync(tmpDir, { recursive: true });
+    try {
+      validateRunDir(tmpDir);
+      assert.fail('should throw');
+    } catch (err) {
+      assert.ok(err instanceof FlowWalkerError);
+      assert.equal(err.code, 'FILE_NOT_FOUND');
+      assert.ok(err.message.includes('run.json'));
+    }
+    rmdirSync(tmpDir);
+  });
+
+  it('rejects path traversal', () => {
+    assert.throws(() => validateRunDir('../../etc'), FlowWalkerError);
+  });
+});

package/tests/yaml-writer.test.ts

@@ -0,0 +1,146 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { generateFlows, toYaml } from '../src/yaml-writer.ts';
+import { NavigationGraph } from '../src/graph.ts';
+import type { Flow } from '../src/types.ts';
+
+describe('generateFlows', () => {
+  it('generates a single-screen flow for isolated nodes', () => {
+    const g = new NavigationGraph();
+    g.addScreen('abc', 'home', ['button'], 5);
+
+    const flows = generateFlows(g);
+    assert.equal(flows.length, 1);
+    assert.equal(flows[0].name, 'home');
+    assert.equal(flows[0].setup, 'normal');
+    assert.ok(flows[0].steps.length >= 1);
+  });
+
+  it('generates one flow per outgoing branch from root', () => {
+    const g = new NavigationGraph();
+    g.addScreen('root', 'home', ['button'], 5);
+    g.addScreen('a', 'settings', ['button'], 8);
+    g.addScreen('b', 'profile', ['button'], 4);
+
+    g.addEdge('root', 'a', { ref: '@e1', type: 'button', text: 'Settings' });
+    g.addEdge('root', 'b', { ref: '@e2', type: 'button', text: 'Profile' });
+
+    const flows = generateFlows(g);
+    assert.equal(flows.length, 2);
+
+    const names = flows.map(f => f.name).sort();
+    assert.deepEqual(names, ['profile', 'settings']);
+  });
+
+  it('includes press, assert, back, and screenshot steps', () => {
+    const g = new NavigationGraph();
+    g.addScreen('root', 'home', ['button'], 5);
+    g.addScreen('a', 'settings', ['button'], 8);
+    g.addEdge('root', 'a', { ref: '@e1', type: 'button', text: 'Settings' });
+
+    const flows = generateFlows(g);
+    const flow = flows[0];
+    const stepNames = flow.steps.map(s => s.name);
+
+    // Should have: verify root, press to settings, verify settings, back to root
+    assert.ok(stepNames.some(n => n.includes('Verify home')));
+    assert.ok(stepNames.some(n => n.includes('Press')));
+    assert.ok(stepNames.some(n => n.includes('Back')));
+
+    // Check assert exists on verify steps
+    const verifyStep = flow.steps.find(s => s.name.includes('Verify home'));
+    assert.ok(verifyStep?.assert?.interactive_count);
+
+    // Check screenshot exists
+    const screenshotSteps = flow.steps.filter(s => s.screenshot);
+    assert.ok(screenshotSteps.length >= 1);
+  });
+
+  it('generates valid flow with correct structure fields', () => {
+    const g = new NavigationGraph();
+    g.addScreen('r', 'home', ['button'], 3);
+    g.addScreen('s', 'settings', ['button'], 5);
+    g.addEdge('r', 's', { ref: '@e1', type: 'button', text: 'Go' });
+
+    const flows = generateFlows(g);
+    const flow = flows[0];
+
+    // All flows must have name, description, setup, steps
+    assert.ok(flow.name);
+    assert.ok(flow.description);
+    assert.equal(flow.setup, 'normal');
+    assert.ok(Array.isArray(flow.steps));
+    assert.ok(flow.steps.length > 0);
+
+    // Each step must have a name
+    for (const step of flow.steps) {
+      assert.ok(step.name, 'every step must have a name');
+    }
+  });
+});
+
+describe('toYaml', () => {
+  it('produces valid YAML with name: and steps: fields', () => {
+    const flow: Flow = {
+      name: 'settings-nav',
+      description: 'Home → Settings navigation',
+      setup: 'normal',
+      steps: [
+        { name: 'Verify home', assert: { interactive_count: { min: 3 } }, screenshot: 'home' },
+        { name: 'Press Settings', press: { type: 'button', hint: 'Settings gear' } },
+        { name: 'Back to home', back: true },
+      ],
+    };
+
+    const yaml = toYaml(flow);
+
+    // Check required YAML fields
+    assert.ok(yaml.includes('name: settings-nav'));
+    assert.ok(yaml.includes('description: Home → Settings navigation'));
+    assert.ok(yaml.includes('setup: normal'));
+    assert.ok(yaml.includes('steps:'));
+
+    // Check step structure
+    assert.ok(yaml.includes('- name: Verify home'));
+    assert.ok(yaml.includes('interactive_count: { min: 3 }'));
+    assert.ok(yaml.includes('screenshot: home'));
+    assert.ok(yaml.includes('press: { type: button, hint: "Settings gear" }'));
+    assert.ok(yaml.includes('back: true'));
+  });
+
+  it('outputs E2E Flow comment header', () => {
+    const flow: Flow = {
+      name: 'test',
+      description: 'A test flow',
+      setup: 'normal',
+      steps: [{ name: 'Step 1' }],
+    };
+
+    const yaml = toYaml(flow);
+    assert.ok(yaml.startsWith('# E2E Flow:'));
+  });
+
+  it('handles flow with assert text field', () => {
+    const flow: Flow = {
+      name: 'chat',
+      description: 'Chat flow',
+      setup: 'normal',
+      steps: [{ name: 'Verify', assert: { text: 'Conversations' } }],
+    };
+
+    const yaml = toYaml(flow);
+    assert.ok(yaml.includes('text: "Conversations"'));
+  });
+
+  it('handles scroll steps', () => {
+    const flow: Flow = {
+      name: 'scroll',
+      description: 'Scroll test',
+      setup: 'normal',
+      steps: [{ name: 'Scroll down', scroll: 'down' }],
+    };
+
+    const yaml = toYaml(flow);
+    assert.ok(yaml.includes('scroll: down'));
+  });
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}