@browserflow-ai/core 0.0.6

package/schemas/spec-v2.schema.json

@@ -0,0 +1,413 @@
+{
+  "$ref": "#/definitions/spec-v2",
+  "definitions": {
+    "spec-v2": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "number",
+          "const": 2
+        },
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$",
+          "errorMessage": {
+            "pattern": "Name must be kebab-case (lowercase letters, numbers, and hyphens only)"
+          }
+        },
+        "description": {
+          "type": "string"
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "errorMessage": {
+                  "minLength": "Step id is required"
+                }
+              },
+              "action": {
+                "type": "string",
+                "enum": [
+                  "click",
+                  "navigate",
+                  "back",
+                  "forward",
+                  "refresh",
+                  "reload",
+                  "fill",
+                  "type",
+                  "select",
+                  "check",
+                  "press",
+                  "upload",
+                  "wait",
+                  "expect",
+                  "screenshot",
+                  "scroll",
+                  "scroll_into_view",
+                  "verify_state",
+                  "identify_element",
+                  "ai_verify",
+                  "custom"
+                ]
+              },
+              "name": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "why": {
+                "type": "string"
+              },
+              "target": {
+                "type": "object",
+                "properties": {
+                  "query": {
+                    "type": "string"
+                  },
+                  "testid": {
+                    "type": "string"
+                  },
+                  "role": {
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "label": {
+                    "type": "string"
+                  },
+                  "placeholder": {
+                    "type": "string"
+                  },
+                  "text": {
+                    "type": "string"
+                  },
+                  "css": {
+                    "type": "string"
+                  },
+                  "within": {},
+                  "nth": {
+                    "type": "integer"
+                  }
+                },
+                "additionalProperties": false
+              },
+              "url": {
+                "type": "string"
+              },
+              "value": {
+                "type": "string"
+              },
+              "text": {
+                "type": "string"
+              },
+              "option": {
+                "type": "string"
+              },
+              "checked": {
+                "type": "boolean"
+              },
+              "duration": {
+                "type": "string"
+              },
+              "state": {
+                "type": "string",
+                "enum": [
+                  "visible",
+                  "hidden",
+                  "enabled",
+                  "disabled",
+                  "checked",
+                  "unchecked",
+                  "focused",
+                  "editable",
+                  "attached",
+                  "detached"
+                ]
+              },
+              "timeout": {
+                "type": "string"
+              },
+              "pressEnter": {
+                "type": "boolean"
+              },
+              "checks": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "element_visible": {
+                      "type": "string"
+                    },
+                    "element_not_visible": {
+                      "type": "string"
+                    },
+                    "text_contains": {
+                      "type": "string"
+                    },
+                    "text_not_contains": {
+                      "type": "string"
+                    },
+                    "url_contains": {
+                      "type": "string"
+                    },
+                    "element_count": {
+                      "type": "object",
+                      "properties": {
+                        "selector": {
+                          "type": "string"
+                        },
+                        "expected": {
+                          "type": "number"
+                        }
+                      },
+                      "required": [
+                        "selector",
+                        "expected"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "attribute": {
+                      "type": "object",
+                      "properties": {
+                        "selector": {
+                          "type": "string"
+                        },
+                        "attribute": {
+                          "type": "string"
+                        },
+                        "equals": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "selector",
+                        "attribute",
+                        "equals"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "highlight": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "selector": {
+                      "type": "string"
+                    },
+                    "label": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "selector"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "mask": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "selector": {
+                      "type": "string"
+                    },
+                    "region": {
+                      "type": "object",
+                      "properties": {
+                        "x": {
+                          "type": "number"
+                        },
+                        "y": {
+                          "type": "number"
+                        },
+                        "width": {
+                          "type": "number"
+                        },
+                        "height": {
+                          "type": "number"
+                        }
+                      },
+                      "required": [
+                        "x",
+                        "y",
+                        "width",
+                        "height"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "reason": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              },
+              "question": {
+                "type": "string"
+              },
+              "expected": {
+                "type": [
+                  "boolean",
+                  "string",
+                  "number"
+                ]
+              },
+              "save_as": {
+                "type": "string"
+              },
+              "ref": {
+                "type": "string"
+              },
+              "selector": {
+                "type": "string"
+              },
+              "for": {
+                "type": "string",
+                "enum": [
+                  "element",
+                  "text",
+                  "url",
+                  "time"
+                ]
+              },
+              "contains": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "action"
+            ],
+            "additionalProperties": false
+          },
+          "minItems": 1,
+          "errorMessage": {
+            "minItems": "At least one step required"
+          }
+        },
+        "timeout": {
+          "type": "string"
+        },
+        "priority": {
+          "type": "string",
+          "enum": [
+            "critical",
+            "high",
+            "normal",
+            "low"
+          ]
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "preconditions": {
+          "type": "object",
+          "properties": {
+            "page": {
+              "type": "object",
+              "properties": {
+                "url": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            "auth": {
+              "type": "object",
+              "properties": {
+                "user": {
+                  "type": "string"
+                },
+                "state": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            "viewport": {
+              "type": "object",
+              "properties": {
+                "width": {
+                  "type": "number"
+                },
+                "height": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "width",
+                "height"
+              ],
+              "additionalProperties": false
+            },
+            "mocks": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "url": {
+                    "type": "string"
+                  },
+                  "response": {}
+                },
+                "required": [
+                  "url"
+                ],
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "expected_outcomes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "description": {
+                "type": "string"
+              },
+              "check": {
+                "type": "string"
+              },
+              "expected": {
+                "type": [
+                  "boolean",
+                  "number",
+                  "string"
+                ]
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "version",
+        "name",
+        "steps"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://browserflow.dev/schemas/spec-v2.schema.json",
+  "title": "BrowserFlow Spec v2",
+  "description": "Schema for BrowserFlow YAML test specifications (version 2)"
+}

package/src/config-schema.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Tests for browserflow.yaml config schema validation
+ */
+
+import { describe, test, expect } from 'bun:test';
+import {
+  browserflowConfigSchema,
+  validateBrowserflowConfig,
+  parseBrowserflowConfig,
+} from './config-schema.js';
+
+describe('browserflowConfigSchema', () => {
+  describe('valid configs', () => {
+    test('accepts minimal config with required project.name', () => {
+      const config = {
+        project: {
+          name: 'my-project',
+        },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(true);
+    });
+
+    test('accepts full config', () => {
+      const config = {
+        project: {
+          name: 'my-project',
+          base_url: 'http://localhost:3000',
+        },
+        runtime: {
+          browser: 'chromium',
+          headless: true,
+          viewport: { width: 1280, height: 720 },
+          timeout: '30s',
+        },
+        locators: {
+          prefer_testid: true,
+          testid_attributes: ['data-testid', 'data-test'],
+        },
+        exploration: {
+          adapter: 'claude',
+          max_retries: 3,
+        },
+        review: {
+          port: 8190,
+          auto_open: true,
+        },
+        output: {
+          tests_dir: 'e2e/tests',
+          baselines_dir: 'baselines',
+        },
+        ci: {
+          fail_on_baseline_diff: false,
+          parallel: 2,
+        },
+      };
+      const result = browserflowConfigSchema.safeParse(config);
+      expect(result.success).toBe(true);
+    });
+
+    test('accepts browser alias for runtime', () => {
+      const config = {
+        project: { name: 'test' },
+        browser: {
+          engine: 'firefox',
+          headless: false,
+        },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(true);
+    });
+
+    test('accepts numeric timeout', () => {
+      const config = {
+        project: { name: 'test' },
+        runtime: {
+          timeout: 30000,
+        },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(true);
+    });
+
+    test('accepts duration string timeout', () => {
+      const config = {
+        project: { name: 'test' },
+        runtime: {
+          timeout: '1m30s',
+        },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(true);
+    });
+  });
+
+  describe('invalid configs', () => {
+    test('rejects missing project', () => {
+      const config = {
+        runtime: { browser: 'chromium' },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(false);
+    });
+
+    test('rejects missing project.name', () => {
+      const config = {
+        project: {},
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(false);
+    });
+
+    test('rejects empty project.name', () => {
+      const config = {
+        project: { name: '' },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(false);
+    });
+
+    test('rejects invalid browser type', () => {
+      const config = {
+        project: { name: 'test' },
+        runtime: {
+          browser: 'chrome', // Invalid - should be chromium
+        },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(false);
+    });
+
+    test('rejects invalid port number', () => {
+      const config = {
+        project: { name: 'test' },
+        review: {
+          port: 70000, // Invalid - max is 65535
+        },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(false);
+    });
+
+    test('rejects negative viewport dimensions', () => {
+      const config = {
+        project: { name: 'test' },
+        runtime: {
+          viewport: { width: -100, height: 720 },
+        },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(false);
+    });
+
+    test('rejects negative max_retries', () => {
+      const config = {
+        project: { name: 'test' },
+        exploration: {
+          max_retries: -1,
+        },
+      };
+      expect(browserflowConfigSchema.safeParse(config).success).toBe(false);
+    });
+  });
+});
+
+describe('validateBrowserflowConfig', () => {
+  test('returns true for valid config', () => {
+    const config = {
+      project: { name: 'test' },
+    };
+    expect(validateBrowserflowConfig(config)).toBe(true);
+  });
+
+  test('returns false for invalid config', () => {
+    const config = {
+      project: {},
+    };
+    expect(validateBrowserflowConfig(config)).toBe(false);
+  });
+});
+
+describe('parseBrowserflowConfig', () => {
+  test('returns data for valid config', () => {
+    const config = {
+      project: { name: 'test' },
+    };
+    const result = parseBrowserflowConfig(config);
+    expect(result.success).toBe(true);
+    expect(result.data?.project.name).toBe('test');
+  });
+
+  test('returns error message for invalid config', () => {
+    const config = {
+      project: { name: '' },
+    };
+    const result = parseBrowserflowConfig(config);
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('project.name');
+  });
+});

package/src/config-schema.ts

@@ -0,0 +1,111 @@
+/**
+ * Zod schema for browserflow.yaml config files
+ *
+ * @see bf-cv6 for implementation task
+ */
+
+import { z } from 'zod';
+import { durationSchema } from './spec-schema.js';
+
+// Browser types supported by Playwright
+export const browserTypeSchema = z.enum(['chromium', 'firefox', 'webkit']);
+
+// Viewport configuration
+export const viewportSchema = z.object({
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+});
+
+// Project section
+export const projectConfigSchema = z.object({
+  name: z.string().min(1),
+  base_url: z.string().url().optional(),
+});
+
+// Runtime/browser section
+export const runtimeConfigSchema = z.object({
+  browser: browserTypeSchema.optional().default('chromium'),
+  engine: browserTypeSchema.optional(), // Alias for browser
+  headless: z.boolean().optional().default(true),
+  viewport: viewportSchema.optional(),
+  timeout: z.union([durationSchema, z.number()]).optional(),
+});
+
+// Locator preferences
+export const locatorsConfigSchema = z.object({
+  prefer_testid: z.boolean().optional().default(true),
+  testid_attributes: z.array(z.string()).optional(),
+});
+
+// Exploration settings
+export const explorationConfigSchema = z.object({
+  adapter: z.string().optional().default('claude'),
+  max_retries: z.number().int().nonnegative().optional().default(3),
+});
+
+// Review UI settings
+export const reviewConfigSchema = z.object({
+  port: z.number().int().min(1).max(65535).optional().default(8190),
+  auto_open: z.boolean().optional().default(true),
+});
+
+// Output paths
+export const outputConfigSchema = z.object({
+  tests_dir: z.string().optional().default('e2e/tests'),
+  baselines_dir: z.string().optional().default('baselines'),
+});
+
+// CI settings
+export const ciConfigSchema = z.object({
+  fail_on_baseline_diff: z.boolean().optional().default(false),
+  parallel: z.number().int().positive().optional(),
+});
+
+// Top-level browserflow.yaml config schema
+export const browserflowConfigSchema = z.object({
+  project: projectConfigSchema,
+  runtime: runtimeConfigSchema.optional(),
+  browser: runtimeConfigSchema.optional(), // Alias for runtime
+  locators: locatorsConfigSchema.optional(),
+  exploration: explorationConfigSchema.optional(),
+  review: reviewConfigSchema.optional(),
+  output: outputConfigSchema.optional(),
+  ci: ciConfigSchema.optional(),
+});
+
+// Type exports
+export type BrowserTypeConfig = z.infer<typeof browserTypeSchema>;
+export type ViewportConfig = z.infer<typeof viewportSchema>;
+export type ProjectConfig = z.infer<typeof projectConfigSchema>;
+export type RuntimeConfig = z.infer<typeof runtimeConfigSchema>;
+export type LocatorsConfig = z.infer<typeof locatorsConfigSchema>;
+export type ExplorationConfig = z.infer<typeof explorationConfigSchema>;
+export type ReviewConfig = z.infer<typeof reviewConfigSchema>;
+export type OutputConfig = z.infer<typeof outputConfigSchema>;
+export type CiConfig = z.infer<typeof ciConfigSchema>;
+export type BrowserflowConfig = z.infer<typeof browserflowConfigSchema>;
+
+/**
+ * Validates a browserflow config object
+ */
+export function validateBrowserflowConfig(config: unknown): config is BrowserflowConfig {
+  return browserflowConfigSchema.safeParse(config).success;
+}
+
+/**
+ * Parses and validates a browserflow config with error details
+ */
+export function parseBrowserflowConfig(config: unknown): {
+  success: boolean;
+  data?: BrowserflowConfig;
+  error?: string;
+} {
+  const result = browserflowConfigSchema.safeParse(config);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  return {
+    success: false,
+    error: result.error.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join('; '),
+  };
+}