@browserflow-ai/core 0.0.6

package/src/locator-object.ts

@@ -0,0 +1,250 @@
+/**
+ * LocatorObject types and resolution utilities
+ *
+ * @see bf-6ig for implementation task
+ */
+
+import { z } from 'zod';
+import type { Page, Locator } from 'playwright-core';
+
+/**
+ * Supported locator strategy types
+ */
+export type LocatorStrategyType = 'testid' | 'role' | 'label' | 'placeholder' | 'text' | 'css';
+
+/**
+ * Locator strategy definition
+ */
+export interface LocatorStrategy {
+  type: LocatorStrategyType;
+  // For testid
+  value?: string;
+  attribute?: string; // Default: data-testid
+  // For role
+  role?: string;
+  name?: string;
+  exact?: boolean; // Default: true
+  // For label/placeholder/text
+  text?: string;
+  // For css
+  selector?: string;
+}
+
+/**
+ * DOM fingerprint for element verification
+ */
+export interface DOMFingerprint {
+  tag: string;
+  classes: string[];
+  attributes?: Record<string, string>;
+}
+
+/**
+ * Bounding box for element position
+ */
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Proof data for element verification
+ */
+export interface LocatorProof {
+  a11y_role?: string;
+  a11y_name?: string;
+  dom_fingerprint?: DOMFingerprint;
+  bounding_box?: BoundingBox;
+}
+
+/**
+ * Scoping constraints for locator
+ */
+export interface LocatorScoping {
+  within?: LocatorStrategy[];
+  nth?: number;
+}
+
+/**
+ * Complete LocatorObject - core primitive for deterministic element selection
+ */
+export interface LocatorObject {
+  locator_id: string;
+  preferred: LocatorStrategy;
+  fallbacks: LocatorStrategy[];
+  scoping?: LocatorScoping;
+  proof: LocatorProof;
+}
+
+/**
+ * Options for resolving locators
+ */
+export interface ResolveOptions {
+  useFallbacks: boolean; // false in CI, true in dev
+  timeout?: number;
+}
+
+// Zod schemas
+export const locatorStrategyTypeSchema = z.enum(['testid', 'role', 'label', 'placeholder', 'text', 'css']);
+
+export const locatorStrategySchema = z.object({
+  type: locatorStrategyTypeSchema,
+  // For testid
+  value: z.string().optional(),
+  attribute: z.string().optional(),
+  // For role
+  role: z.string().optional(),
+  name: z.string().optional(),
+  exact: z.boolean().optional(),
+  // For label/placeholder/text
+  text: z.string().optional(),
+  // For css
+  selector: z.string().optional(),
+});
+
+export const domFingerprintSchema = z.object({
+  tag: z.string(),
+  classes: z.array(z.string()),
+  attributes: z.record(z.string()).optional(),
+});
+
+export const boundingBoxSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  width: z.number(),
+  height: z.number(),
+});
+
+export const locatorProofSchema = z.object({
+  a11y_role: z.string().optional(),
+  a11y_name: z.string().optional(),
+  dom_fingerprint: domFingerprintSchema.optional(),
+  bounding_box: boundingBoxSchema.optional(),
+});
+
+export const locatorScopingSchema = z.object({
+  within: z.array(locatorStrategySchema).optional(),
+  nth: z.number().int().optional(),
+});
+
+export const locatorObjectSchema = z.object({
+  locator_id: z.string().min(1),
+  preferred: locatorStrategySchema,
+  fallbacks: z.array(locatorStrategySchema),
+  scoping: locatorScopingSchema.optional(),
+  proof: locatorProofSchema,
+});
+
+/**
+ * Converts a LocatorStrategy to a Playwright Locator
+ */
+export function strategyToLocator(strategy: LocatorStrategy, page: Page): Locator {
+  switch (strategy.type) {
+    case 'testid':
+      if (strategy.attribute && strategy.attribute !== 'data-testid') {
+        // Custom testid attribute
+        return page.locator(`[${strategy.attribute}="${strategy.value}"]`);
+      }
+      return page.getByTestId(strategy.value!);
+
+    case 'role':
+      const roleOptions: { name?: string; exact?: boolean } = {};
+      if (strategy.name) {
+        roleOptions.name = strategy.name;
+        roleOptions.exact = strategy.exact ?? true;
+      }
+      return page.getByRole(strategy.role as any, roleOptions);
+
+    case 'label':
+      return page.getByLabel(strategy.text!);
+
+    case 'placeholder':
+      return page.getByPlaceholder(strategy.text!);
+
+    case 'text':
+      return page.getByText(strategy.text!);
+
+    case 'css':
+      return page.locator(strategy.selector!);
+
+    default:
+      throw new Error(`Unknown locator strategy type: ${(strategy as any).type}`);
+  }
+}
+
+/**
+ * Resolves a LocatorObject to a Playwright Locator
+ */
+export function resolveLocator(
+  locatorObj: LocatorObject,
+  page: Page,
+  options: ResolveOptions
+): Locator {
+  // Start with preferred strategy
+  let locator = strategyToLocator(locatorObj.preferred, page);
+
+  // Apply scoping constraints
+  if (locatorObj.scoping?.within) {
+    for (const scope of locatorObj.scoping.within) {
+      const scopeLocator = strategyToLocator(scope, page);
+      locator = scopeLocator.locator(locator);
+    }
+  }
+
+  if (locatorObj.scoping?.nth !== undefined) {
+    locator = locator.nth(locatorObj.scoping.nth);
+  }
+
+  // TODO: If useFallbacks is true and locator doesn't find element,
+  // iterate through fallbacks. This requires async operation.
+
+  return locator;
+}
+
+// Legacy exports for backwards compatibility
+export type LocatorMethod =
+  | 'getByRole'
+  | 'getByText'
+  | 'getByLabel'
+  | 'getByPlaceholder'
+  | 'getByTestId'
+  | 'getByAltText'
+  | 'getByTitle'
+  | 'locator';
+
+export interface LocatorArgs {
+  role?: string;
+  name?: string | RegExp;
+  text?: string | RegExp;
+  testId?: string;
+  exact?: boolean;
+  selector?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Legacy LocatorObject interface (for backwards compatibility)
+ */
+export interface LegacyLocatorObject {
+  ref?: string;
+  selector?: string;
+  method?: LocatorMethod;
+  args?: LocatorArgs;
+  description?: string;
+}
+
+/**
+ * Legacy function - resolves a LegacyLocatorObject to a string representation
+ */
+export function resolveLegacyLocator(locator: LegacyLocatorObject): string {
+  if (locator.selector) {
+    return `locator(${JSON.stringify(locator.selector)})`;
+  }
+  if (locator.method && locator.args) {
+    const argsStr = JSON.stringify(locator.args);
+    return `${locator.method}(${argsStr})`;
+  }
+  return 'locator("body")';
+}

package/src/lockfile.test.ts

@@ -0,0 +1,345 @@
+/**
+ * Tests for lockfile types
+ * @see bf-aak
+ */
+
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { join } from 'path';
+import { mkdtemp, rm, mkdir, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import {
+  lockfileSchema,
+  maskSchema,
+  assertionSchema,
+  readLockfile,
+  writeLockfile,
+  validateLockfile,
+  computeSpecHash,
+  type Lockfile,
+  type Mask,
+  type Assertion,
+  type AssertionType,
+} from './lockfile.js';
+
+describe('maskSchema', () => {
+  test('validates mask with coordinates', () => {
+    const mask: Mask = {
+      x: 100,
+      y: 200,
+      width: 50,
+      height: 30,
+      reason: 'Dynamic content',
+    };
+    expect(maskSchema.safeParse(mask).success).toBe(true);
+  });
+
+  test('validates mask with locator', () => {
+    const mask: Mask = {
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+      reason: 'User avatar',
+      locator: '[data-testid="avatar"]',
+    };
+    expect(maskSchema.safeParse(mask).success).toBe(true);
+  });
+
+  test('requires all coordinate fields', () => {
+    const incompleteMask = {
+      x: 100,
+      y: 200,
+      reason: 'Missing dimensions',
+    };
+    expect(maskSchema.safeParse(incompleteMask).success).toBe(false);
+  });
+});
+
+describe('assertionSchema', () => {
+  const assertionTypes: AssertionType[] = [
+    'visible',
+    'hidden',
+    'text_contains',
+    'text_equals',
+    'url_contains',
+    'url_matches',
+    'count',
+    'attribute',
+    'checked',
+    'screenshot',
+  ];
+
+  for (const type of assertionTypes) {
+    test(`validates ${type} assertion type`, () => {
+      const assertion: Assertion = {
+        id: `assertion-${type}`,
+        type,
+      };
+      expect(assertionSchema.safeParse(assertion).success).toBe(true);
+    });
+  }
+
+  test('validates assertion with target', () => {
+    const assertion: Assertion = {
+      id: 'assert-1',
+      type: 'visible',
+      target: {
+        locator_id: 'loc-1',
+        preferred: { type: 'testid', value: 'submit-btn' },
+        fallbacks: [],
+        proof: {},
+      },
+    };
+    expect(assertionSchema.safeParse(assertion).success).toBe(true);
+  });
+
+  test('validates assertion with expected value', () => {
+    const assertion: Assertion = {
+      id: 'assert-2',
+      type: 'text_equals',
+      expected: 'Welcome back!',
+    };
+    expect(assertionSchema.safeParse(assertion).success).toBe(true);
+  });
+
+  test('validates assertion attached to step', () => {
+    const assertion: Assertion = {
+      id: 'assert-3',
+      type: 'screenshot',
+      step_id: 'step-5',
+    };
+    expect(assertionSchema.safeParse(assertion).success).toBe(true);
+  });
+});
+
+describe('lockfileSchema', () => {
+  test('validates complete lockfile', () => {
+    const lockfile: Lockfile = {
+      run_id: 'run-20260115031000-abc123',
+      spec_name: 'checkout-cart',
+      spec_hash: 'abc123def456',
+      created_at: '2026-01-15T03:10:00Z',
+      locators: {
+        'submit-btn': {
+          locator_id: 'submit-btn',
+          preferred: { type: 'testid', value: 'submit-btn' },
+          fallbacks: [],
+          proof: { a11y_role: 'button' },
+        },
+      },
+      masks: {
+        'checkout-complete': [
+          { x: 10, y: 20, width: 100, height: 50, reason: 'Dynamic timestamp' },
+        ],
+      },
+      assertions: [
+        { id: 'assert-1', type: 'visible' },
+      ],
+      generation: {
+        format: 'playwright-ts',
+        output_path: 'tests/checkout-cart.spec.ts',
+      },
+    };
+    expect(lockfileSchema.safeParse(lockfile).success).toBe(true);
+  });
+
+  test('validates lockfile with generated_at', () => {
+    const lockfile: Lockfile = {
+      run_id: 'run-20260115031000-abc123',
+      spec_name: 'checkout-cart',
+      spec_hash: 'abc123def456',
+      created_at: '2026-01-15T03:10:00Z',
+      locators: {},
+      masks: {},
+      assertions: [],
+      generation: {
+        format: 'playwright-ts',
+        output_path: 'tests/checkout-cart.spec.ts',
+        generated_at: '2026-01-15T03:15:00Z',
+      },
+    };
+    expect(lockfileSchema.safeParse(lockfile).success).toBe(true);
+  });
+
+  test('requires run_id', () => {
+    const lockfile = {
+      spec_name: 'checkout-cart',
+      spec_hash: 'abc123',
+      created_at: '2026-01-15T03:10:00Z',
+      locators: {},
+      masks: {},
+      assertions: [],
+      generation: {
+        format: 'playwright-ts',
+        output_path: 'tests/test.spec.ts',
+      },
+    };
+    expect(lockfileSchema.safeParse(lockfile).success).toBe(false);
+  });
+
+  test('requires spec_name', () => {
+    const lockfile = {
+      run_id: 'run-123',
+      spec_hash: 'abc123',
+      created_at: '2026-01-15T03:10:00Z',
+      locators: {},
+      masks: {},
+      assertions: [],
+      generation: {
+        format: 'playwright-ts',
+        output_path: 'tests/test.spec.ts',
+      },
+    };
+    expect(lockfileSchema.safeParse(lockfile).success).toBe(false);
+  });
+});
+
+describe('validateLockfile', () => {
+  test('returns true for valid lockfile', () => {
+    const lockfile: Lockfile = {
+      run_id: 'run-123',
+      spec_name: 'test',
+      spec_hash: 'abc',
+      created_at: '2026-01-15T03:10:00Z',
+      locators: {},
+      masks: {},
+      assertions: [],
+      generation: {
+        format: 'playwright-ts',
+        output_path: 'tests/test.spec.ts',
+      },
+    };
+    expect(validateLockfile(lockfile)).toBe(true);
+  });
+
+  test('returns false for invalid lockfile', () => {
+    const invalid = {
+      run_id: 'run-123',
+      // Missing required fields
+    };
+    expect(validateLockfile(invalid)).toBe(false);
+  });
+
+  test('returns false for non-object', () => {
+    expect(validateLockfile('string')).toBe(false);
+    expect(validateLockfile(123)).toBe(false);
+    expect(validateLockfile(null)).toBe(false);
+  });
+});
+
+describe('computeSpecHash', () => {
+  test('computes consistent hash for same content', () => {
+    const content = 'version: 2\nname: test';
+    const hash1 = computeSpecHash(content);
+    const hash2 = computeSpecHash(content);
+    expect(hash1).toBe(hash2);
+  });
+
+  test('computes different hash for different content', () => {
+    const hash1 = computeSpecHash('content1');
+    const hash2 = computeSpecHash('content2');
+    expect(hash1).not.toBe(hash2);
+  });
+
+  test('returns SHA256 hex string', () => {
+    const hash = computeSpecHash('test');
+    expect(hash).toMatch(/^[a-f0-9]{64}$/);
+  });
+});
+
+describe('file operations', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'lockfile-test-'));
+    await mkdir(join(tempDir, 'runs', 'test-spec', 'run-123'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('writeLockfile', () => {
+    test('writes lockfile to correct path', async () => {
+      const runDir = join(tempDir, 'runs', 'test-spec', 'run-123');
+      const lockfile: Lockfile = {
+        run_id: 'run-123',
+        spec_name: 'test-spec',
+        spec_hash: 'abc123',
+        created_at: '2026-01-15T03:10:00Z',
+        locators: {},
+        masks: {},
+        assertions: [],
+        generation: {
+          format: 'playwright-ts',
+          output_path: 'tests/test.spec.ts',
+        },
+      };
+
+      await writeLockfile(runDir, lockfile);
+
+      const file = Bun.file(join(runDir, 'lockfile.json'));
+      const content = await file.json();
+      expect(content.run_id).toBe('run-123');
+      expect(content.spec_name).toBe('test-spec');
+    });
+
+    test('writes formatted JSON', async () => {
+      const runDir = join(tempDir, 'runs', 'test-spec', 'run-123');
+      const lockfile: Lockfile = {
+        run_id: 'run-123',
+        spec_name: 'test-spec',
+        spec_hash: 'abc123',
+        created_at: '2026-01-15T03:10:00Z',
+        locators: {},
+        masks: {},
+        assertions: [],
+        generation: {
+          format: 'playwright-ts',
+          output_path: 'tests/test.spec.ts',
+        },
+      };
+
+      await writeLockfile(runDir, lockfile);
+
+      const text = await Bun.file(join(runDir, 'lockfile.json')).text();
+      expect(text).toContain('\n'); // Should be pretty-printed
+    });
+  });
+
+  describe('readLockfile', () => {
+    test('reads lockfile from correct path', async () => {
+      const runDir = join(tempDir, 'runs', 'test-spec', 'run-123');
+      const lockfile: Lockfile = {
+        run_id: 'run-123',
+        spec_name: 'test-spec',
+        spec_hash: 'abc123',
+        created_at: '2026-01-15T03:10:00Z',
+        locators: {},
+        masks: {},
+        assertions: [],
+        generation: {
+          format: 'playwright-ts',
+          output_path: 'tests/test.spec.ts',
+        },
+      };
+
+      await writeFile(join(runDir, 'lockfile.json'), JSON.stringify(lockfile));
+
+      const result = await readLockfile(runDir);
+      expect(result.run_id).toBe('run-123');
+      expect(result.spec_name).toBe('test-spec');
+    });
+
+    test('throws for missing lockfile', async () => {
+      const runDir = join(tempDir, 'runs', 'nonexistent');
+      await expect(readLockfile(runDir)).rejects.toThrow();
+    });
+
+    test('throws for invalid JSON', async () => {
+      const runDir = join(tempDir, 'runs', 'test-spec', 'run-123');
+      await writeFile(join(runDir, 'lockfile.json'), 'not json');
+      await expect(readLockfile(runDir)).rejects.toThrow();
+    });
+  });
+});