@browserflow-ai/core 0.0.6

package/src/json-schemas.test.ts

@@ -0,0 +1,374 @@
+/**
+ * Tests for generated JSON schemas
+ *
+ * Validates that the generated JSON schemas correctly accept/reject data
+ */
+
+import { describe, test, expect, beforeAll } from 'bun:test';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEMAS_DIR = join(__dirname, '../schemas');
+
+interface JsonSchema {
+  $schema: string;
+  $id: string;
+  title: string;
+  description: string;
+  [key: string]: unknown;
+}
+
+let ajv: Ajv;
+let specSchema: JsonSchema;
+let configSchema: JsonSchema;
+let lockfileSchema: JsonSchema;
+
+beforeAll(async () => {
+  // Initialize Ajv with format support
+  ajv = new Ajv({
+    allErrors: true,
+    strict: false, // Allow draft-07 features
+  });
+  addFormats(ajv);
+
+  // Load all schemas
+  specSchema = JSON.parse(await readFile(join(SCHEMAS_DIR, 'spec-v2.schema.json'), 'utf-8'));
+  configSchema = JSON.parse(await readFile(join(SCHEMAS_DIR, 'browserflow.schema.json'), 'utf-8'));
+  lockfileSchema = JSON.parse(await readFile(join(SCHEMAS_DIR, 'lockfile.schema.json'), 'utf-8'));
+});
+
+describe('spec-v2.schema.json', () => {
+  test('validates a valid spec', () => {
+    const spec = {
+      version: 2,
+      name: 'test-spec',
+      steps: [
+        {
+          id: 'step-1',
+          action: 'navigate',
+          url: 'https://example.com',
+        },
+      ],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(true);
+  });
+
+  test('validates spec with target', () => {
+    const spec = {
+      version: 2,
+      name: 'click-test',
+      steps: [
+        {
+          id: 'click-btn',
+          action: 'click',
+          target: {
+            testid: 'submit-button',
+          },
+        },
+      ],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(true);
+  });
+
+  test('rejects spec without version', () => {
+    const spec = {
+      name: 'test-spec',
+      steps: [{ id: 'step-1', action: 'navigate' }],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(false);
+  });
+
+  test('rejects spec with invalid name format', () => {
+    const spec = {
+      version: 2,
+      name: 'Test Spec', // Should be kebab-case
+      steps: [{ id: 'step-1', action: 'navigate' }],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(false);
+  });
+
+  test('rejects spec without steps', () => {
+    const spec = {
+      version: 2,
+      name: 'test-spec',
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(false);
+  });
+
+  test('rejects spec with empty steps', () => {
+    const spec = {
+      version: 2,
+      name: 'test-spec',
+      steps: [],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(false);
+  });
+
+  test('rejects step without id', () => {
+    const spec = {
+      version: 2,
+      name: 'test-spec',
+      steps: [{ action: 'navigate' }],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(false);
+  });
+
+  test('rejects invalid action type', () => {
+    const spec = {
+      version: 2,
+      name: 'test-spec',
+      steps: [{ id: 'step-1', action: 'invalid_action' }],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(false);
+  });
+
+  test('validates spec with reload action', () => {
+    const spec = {
+      version: 2,
+      name: 'reload-test',
+      steps: [
+        {
+          id: 'reload-page',
+          action: 'reload',
+        },
+      ],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(true);
+  });
+
+  test('validates spec with scroll action', () => {
+    const spec = {
+      version: 2,
+      name: 'scroll-test',
+      steps: [
+        {
+          id: 'scroll-down',
+          action: 'scroll',
+          target: { css: '.content' },
+        },
+      ],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(true);
+  });
+
+  test('validates spec with press action', () => {
+    const spec = {
+      version: 2,
+      name: 'press-test',
+      steps: [
+        {
+          id: 'press-enter',
+          action: 'press',
+          value: 'Enter',
+        },
+      ],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(true);
+  });
+
+  test('validates spec with upload action', () => {
+    const spec = {
+      version: 2,
+      name: 'upload-test',
+      steps: [
+        {
+          id: 'upload-file',
+          action: 'upload',
+          target: { testid: 'file-input' },
+          value: './test-file.pdf',
+        },
+      ],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(true);
+  });
+
+  test('validates spec with scroll_into_view action', () => {
+    const spec = {
+      version: 2,
+      name: 'scroll-into-view-test',
+      steps: [
+        {
+          id: 'scroll-element',
+          action: 'scroll_into_view',
+          target: { css: '#footer' },
+        },
+      ],
+    };
+    const validate = ajv.compile(specSchema);
+    const valid = validate(spec);
+    expect(valid).toBe(true);
+  });
+});
+
+describe('browserflow.schema.json', () => {
+  test('validates a valid config', () => {
+    const config = {
+      project: {
+        name: 'my-project',
+        base_url: 'http://localhost:3000',
+      },
+      runtime: {
+        browser: 'chromium',
+        headless: true,
+      },
+    };
+    const validate = ajv.compile(configSchema);
+    const valid = validate(config);
+    expect(valid).toBe(true);
+  });
+
+  test('validates minimal config', () => {
+    const config = {
+      project: { name: 'test' },
+    };
+    const validate = ajv.compile(configSchema);
+    const valid = validate(config);
+    expect(valid).toBe(true);
+  });
+
+  test('rejects config without project', () => {
+    const config = {
+      runtime: { browser: 'chromium' },
+    };
+    const validate = ajv.compile(configSchema);
+    const valid = validate(config);
+    expect(valid).toBe(false);
+  });
+
+  test('rejects invalid browser type', () => {
+    const config = {
+      project: { name: 'test' },
+      runtime: { browser: 'chrome' }, // Invalid
+    };
+    const validate = ajv.compile(configSchema);
+    const valid = validate(config);
+    expect(valid).toBe(false);
+  });
+});
+
+describe('lockfile.schema.json', () => {
+  test('validates a valid lockfile', () => {
+    const lockfile = {
+      run_id: 'run-123',
+      spec_name: 'test-spec',
+      spec_hash: 'abc123',
+      created_at: '2026-01-15T00:00:00Z',
+      locators: {},
+      masks: {},
+      assertions: [],
+      generation: {
+        format: 'playwright-ts',
+        output_path: 'e2e/tests/test-spec.spec.ts',
+      },
+    };
+    const validate = ajv.compile(lockfileSchema);
+    const valid = validate(lockfile);
+    expect(valid).toBe(true);
+  });
+
+  test('validates lockfile with locators', () => {
+    const lockfile = {
+      run_id: 'run-123',
+      spec_name: 'test-spec',
+      spec_hash: 'abc123',
+      created_at: '2026-01-15T00:00:00Z',
+      locators: {
+        'step-1': {
+          locator_id: 'loc-1',
+          preferred: {
+            type: 'testid',
+            value: 'submit-btn',
+          },
+          fallbacks: [],
+          proof: {},
+        },
+      },
+      masks: {},
+      assertions: [],
+      generation: {
+        format: 'playwright-ts',
+        output_path: 'e2e/tests/test-spec.spec.ts',
+      },
+    };
+    const validate = ajv.compile(lockfileSchema);
+    const valid = validate(lockfile);
+    expect(valid).toBe(true);
+  });
+
+  test('rejects lockfile missing required fields', () => {
+    const lockfile = {
+      run_id: 'run-123',
+      // Missing spec_name, spec_hash, etc.
+    };
+    const validate = ajv.compile(lockfileSchema);
+    const valid = validate(lockfile);
+    expect(valid).toBe(false);
+  });
+
+  test('rejects lockfile with invalid generation format', () => {
+    const lockfile = {
+      run_id: 'run-123',
+      spec_name: 'test-spec',
+      spec_hash: 'abc123',
+      created_at: '2026-01-15T00:00:00Z',
+      locators: {},
+      masks: {},
+      assertions: [],
+      generation: {
+        format: 'invalid-format', // Should be playwright-ts
+        output_path: 'test.ts',
+      },
+    };
+    const validate = ajv.compile(lockfileSchema);
+    const valid = validate(lockfile);
+    expect(valid).toBe(false);
+  });
+});
+
+describe('schema metadata', () => {
+  test('spec schema has correct metadata', () => {
+    expect(specSchema.$id).toContain('spec-v2.schema.json');
+    expect(specSchema.title).toBe('BrowserFlow Spec v2');
+    expect(specSchema.description).toContain('test specifications');
+  });
+
+  test('config schema has correct metadata', () => {
+    expect(configSchema.$id).toContain('browserflow.schema.json');
+    expect(configSchema.title).toBe('BrowserFlow Configuration');
+    expect(configSchema.description).toContain('configuration files');
+  });
+
+  test('lockfile schema has correct metadata', () => {
+    expect(lockfileSchema.$id).toContain('lockfile.schema.json');
+    expect(lockfileSchema.title).toBe('BrowserFlow Lockfile');
+    expect(lockfileSchema.description).toContain('lockfile.json');
+  });
+});

package/src/locator-object.test.ts

@@ -0,0 +1,323 @@
+/**
+ * Tests for LocatorObject types and resolution
+ * @see bf-6ig
+ */
+
+import { describe, expect, test, mock } from 'bun:test';
+import {
+  locatorObjectSchema,
+  locatorStrategySchema,
+  strategyToLocator,
+  resolveLocator,
+  type LocatorObject,
+  type LocatorStrategy,
+} from './locator-object.js';
+
+describe('locatorStrategySchema', () => {
+  test('validates testid strategy', () => {
+    const result = locatorStrategySchema.safeParse({
+      type: 'testid',
+      value: 'submit-button',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('validates testid with custom attribute', () => {
+    const result = locatorStrategySchema.safeParse({
+      type: 'testid',
+      value: 'submit-button',
+      attribute: 'data-qa',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('validates role strategy', () => {
+    const result = locatorStrategySchema.safeParse({
+      type: 'role',
+      role: 'button',
+      name: 'Submit',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('validates role with exact matching', () => {
+    const result = locatorStrategySchema.safeParse({
+      type: 'role',
+      role: 'button',
+      name: 'Submit',
+      exact: false,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('validates label strategy', () => {
+    const result = locatorStrategySchema.safeParse({
+      type: 'label',
+      text: 'Email Address',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('validates placeholder strategy', () => {
+    const result = locatorStrategySchema.safeParse({
+      type: 'placeholder',
+      text: 'Enter your email',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('validates text strategy', () => {
+    const result = locatorStrategySchema.safeParse({
+      type: 'text',
+      text: 'Click here',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('validates css strategy', () => {
+    const result = locatorStrategySchema.safeParse({
+      type: 'css',
+      selector: '.submit-btn',
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test('rejects invalid strategy type', () => {
+    const result = locatorStrategySchema.safeParse({
+      type: 'invalid',
+      value: 'test',
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('locatorObjectSchema', () => {
+  test('validates complete locator object', () => {
+    const locatorObj: LocatorObject = {
+      locator_id: 'loc-123',
+      preferred: { type: 'testid', value: 'submit-btn' },
+      fallbacks: [
+        { type: 'role', role: 'button', name: 'Submit' },
+        { type: 'css', selector: '.submit-btn' },
+      ],
+      proof: {
+        a11y_role: 'button',
+        a11y_name: 'Submit',
+      },
+    };
+    const result = locatorObjectSchema.safeParse(locatorObj);
+    expect(result.success).toBe(true);
+  });
+
+  test('validates locator with scoping', () => {
+    const locatorObj: LocatorObject = {
+      locator_id: 'loc-456',
+      preferred: { type: 'role', role: 'button', name: 'Delete' },
+      fallbacks: [],
+      scoping: {
+        within: [{ type: 'testid', value: 'user-list' }],
+        nth: 2,
+      },
+      proof: {},
+    };
+    const result = locatorObjectSchema.safeParse(locatorObj);
+    expect(result.success).toBe(true);
+  });
+
+  test('validates locator with DOM fingerprint', () => {
+    const locatorObj: LocatorObject = {
+      locator_id: 'loc-789',
+      preferred: { type: 'css', selector: 'button.primary' },
+      fallbacks: [],
+      proof: {
+        dom_fingerprint: {
+          tag: 'button',
+          classes: ['primary', 'submit'],
+          attributes: { type: 'submit' },
+        },
+      },
+    };
+    const result = locatorObjectSchema.safeParse(locatorObj);
+    expect(result.success).toBe(true);
+  });
+
+  test('validates locator with bounding box', () => {
+    const locatorObj: LocatorObject = {
+      locator_id: 'loc-abc',
+      preferred: { type: 'testid', value: 'btn' },
+      fallbacks: [],
+      proof: {
+        bounding_box: { x: 100, y: 200, width: 50, height: 30 },
+      },
+    };
+    const result = locatorObjectSchema.safeParse(locatorObj);
+    expect(result.success).toBe(true);
+  });
+
+  test('requires locator_id', () => {
+    const result = locatorObjectSchema.safeParse({
+      preferred: { type: 'testid', value: 'btn' },
+      fallbacks: [],
+      proof: {},
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test('requires preferred strategy', () => {
+    const result = locatorObjectSchema.safeParse({
+      locator_id: 'loc-123',
+      fallbacks: [],
+      proof: {},
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('strategyToLocator', () => {
+  // Mock Playwright Page object
+  const mockPage = {
+    getByTestId: mock((id: string) => ({ _testid: id })),
+    getByRole: mock((role: string, options?: { name?: string; exact?: boolean }) => ({
+      _role: role,
+      _options: options,
+    })),
+    getByLabel: mock((text: string) => ({ _label: text })),
+    getByPlaceholder: mock((text: string) => ({ _placeholder: text })),
+    getByText: mock((text: string) => ({ _text: text })),
+    locator: mock((selector: string) => ({ _selector: selector })),
+  };
+
+  test('converts testid strategy', () => {
+    const strategy: LocatorStrategy = { type: 'testid', value: 'submit-btn' };
+    const result = strategyToLocator(strategy, mockPage as any);
+    expect(mockPage.getByTestId).toHaveBeenCalledWith('submit-btn');
+  });
+
+  test('converts testid with custom attribute', () => {
+    const strategy: LocatorStrategy = {
+      type: 'testid',
+      value: 'submit-btn',
+      attribute: 'data-qa',
+    };
+    const result = strategyToLocator(strategy, mockPage as any);
+    expect(mockPage.locator).toHaveBeenCalledWith('[data-qa="submit-btn"]');
+  });
+
+  test('converts role strategy', () => {
+    const strategy: LocatorStrategy = {
+      type: 'role',
+      role: 'button',
+      name: 'Submit',
+    };
+    strategyToLocator(strategy, mockPage as any);
+    expect(mockPage.getByRole).toHaveBeenCalledWith('button', {
+      name: 'Submit',
+      exact: true,
+    });
+  });
+
+  test('converts role with exact=false', () => {
+    const strategy: LocatorStrategy = {
+      type: 'role',
+      role: 'button',
+      name: 'Submit',
+      exact: false,
+    };
+    strategyToLocator(strategy, mockPage as any);
+    expect(mockPage.getByRole).toHaveBeenCalledWith('button', {
+      name: 'Submit',
+      exact: false,
+    });
+  });
+
+  test('converts label strategy', () => {
+    const strategy: LocatorStrategy = { type: 'label', text: 'Email' };
+    strategyToLocator(strategy, mockPage as any);
+    expect(mockPage.getByLabel).toHaveBeenCalledWith('Email');
+  });
+
+  test('converts placeholder strategy', () => {
+    const strategy: LocatorStrategy = {
+      type: 'placeholder',
+      text: 'Enter email',
+    };
+    strategyToLocator(strategy, mockPage as any);
+    expect(mockPage.getByPlaceholder).toHaveBeenCalledWith('Enter email');
+  });
+
+  test('converts text strategy', () => {
+    const strategy: LocatorStrategy = { type: 'text', text: 'Click here' };
+    strategyToLocator(strategy, mockPage as any);
+    expect(mockPage.getByText).toHaveBeenCalledWith('Click here');
+  });
+
+  test('converts css strategy', () => {
+    const strategy: LocatorStrategy = { type: 'css', selector: '.submit-btn' };
+    strategyToLocator(strategy, mockPage as any);
+    expect(mockPage.locator).toHaveBeenCalledWith('.submit-btn');
+  });
+});
+
+describe('resolveLocator', () => {
+  // Mock Playwright Page with chainable locator
+  const createMockPage = () => {
+    const locatorResult = {
+      _selector: '',
+      nth: mock((n: number) => ({ ...locatorResult, _nth: n })),
+      locator: mock((loc: any) => ({ ...locatorResult, _chained: loc })),
+    };
+
+    return {
+      getByTestId: mock((id: string) => ({ ...locatorResult, _testid: id })),
+      getByRole: mock((role: string, options?: any) => ({
+        ...locatorResult,
+        _role: role,
+        _options: options,
+      })),
+      getByLabel: mock(() => locatorResult),
+      getByPlaceholder: mock(() => locatorResult),
+      getByText: mock(() => locatorResult),
+      locator: mock((selector: string) => ({ ...locatorResult, _selector: selector })),
+    };
+  };
+
+  test('resolves locator using preferred strategy', () => {
+    const mockPage = createMockPage();
+    const locator: LocatorObject = {
+      locator_id: 'loc-1',
+      preferred: { type: 'testid', value: 'submit-btn' },
+      fallbacks: [],
+      proof: {},
+    };
+    resolveLocator(locator, mockPage as any, { useFallbacks: false });
+    expect(mockPage.getByTestId).toHaveBeenCalledWith('submit-btn');
+  });
+
+  test('applies nth scoping', () => {
+    const mockPage = createMockPage();
+    const locator: LocatorObject = {
+      locator_id: 'loc-2',
+      preferred: { type: 'role', role: 'listitem' },
+      fallbacks: [],
+      scoping: { nth: 2 },
+      proof: {},
+    };
+    const result = resolveLocator(locator, mockPage as any, { useFallbacks: false });
+    expect(result._nth).toBe(2);
+  });
+
+  test('applies within scoping', () => {
+    const mockPage = createMockPage();
+    const locator: LocatorObject = {
+      locator_id: 'loc-3',
+      preferred: { type: 'role', role: 'button', name: 'Delete' },
+      fallbacks: [],
+      scoping: {
+        within: [{ type: 'testid', value: 'user-list' }],
+      },
+      proof: {},
+    };
+    resolveLocator(locator, mockPage as any, { useFallbacks: false });
+    expect(mockPage.getByTestId).toHaveBeenCalledWith('user-list');
+  });
+});