@popoverai/dotrequirements 0.19.0 → 0.20.0

package/README.md

@@ -164,6 +164,37 @@ dotreq test
 dotreq test --file .requirements/auth.requirements.md
 ```
 
+### `dotreq browsertest`
+
+Run browser-based acceptance tests against requirements. Uses AI-powered browser automation to verify that your application behaves as specified.
+
+```bash
+dotreq browsertest LOGIN-1
+dotreq browsertest LOGIN-1 https://example.com
+dotreq browsertest LOGIN-1 --json
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output results as JSON (for CI/CD integration) |
+
+**Configuration required:**
+
+Browser testing requires credentials in `project-settings.json`:
+
+```json
+{
+  "defaultURL": "https://your-app.com",
+  "browserTest": {
+    "geminiApiKey": "your-gemini-api-key"
+  }
+}
+```
+
+Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjectId`.
+
 ### `dotreq mcp-setup`
 
 Configure the MCP server for AI assistants (Claude Code, Cursor, etc.).

package/dist/cli.js

@@ -5,6 +5,7 @@ import { linkCommand } from './commands/link.js';
 import { pullCommand } from './commands/pull.js';
 import { pushCommand } from './commands/push.js';
 import { testCommand } from './commands/test.js';
+import { browserTestCommand } from './commands/browsertest.js';
 import { mcpCommand } from './commands/mcp.js';
 import { mcpSetupCommand } from './commands/mcp-setup.js';
 import { loadEnvFile } from './utils/env.js';
@@ -70,6 +71,11 @@ program
     .description('Validate requirements files in .requirements/')
     .option('-f, --file <path>', 'Specific file to validate')
     .action(wrapCommand(testCommand));
+program
+    .command('browsertest <requirement-key> [url]')
+    .description('Run browser-based acceptance test for a requirement')
+    .option('--json', 'Output results as JSON')
+    .action(wrapCommand(browserTestCommand));
 program
     .command('mcp')
     .description('Start the MCP (Model Context Protocol) server for AI assistant integration')

package/dist/commands/browsertest.d.ts

@@ -0,0 +1,6 @@
+interface BrowserTestOptions {
+    json?: boolean;
+}
+export declare function browserTestCommand(requirementKey: string, url: string | undefined, options: BrowserTestOptions): Promise<void>;
+export {};
+//# sourceMappingURL=browsertest.d.ts.map

package/dist/commands/browsertest.js

@@ -0,0 +1,167 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { getProjectInfo, readProjectSettings, } from '../utils/project-settings.js';
+import { loadAllRequirements, getRequirementTree, formatRequirement, } from '../mcp/requirements.js';
+const execFileAsync = promisify(execFile);
+export async function browserTestCommand(requirementKey, url, options) {
+    // 1. Find project and load settings
+    const projectInfo = getProjectInfo();
+    if (!projectInfo) {
+        console.error('Error: No dotrequirements project found.');
+        console.log('Run "dotrequirements init" to create one.');
+        process.exit(1);
+    }
+    let settings;
+    try {
+        settings = readProjectSettings(projectInfo.rootPath);
+    }
+    catch (err) {
+        // Settings file exists but is invalid
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+    // 2. Determine URL
+    const targetURL = url || settings?.defaultURL;
+    if (!targetURL) {
+        console.error('Error: No URL provided and no defaultURL in project-settings.json.');
+        console.log('Either provide a URL argument or add "defaultURL" to .requirements/project-settings.json');
+        process.exit(1);
+    }
+    // 3. Check for required credentials
+    const geminiApiKey = settings?.browserTest?.geminiApiKey;
+    if (!geminiApiKey) {
+        console.error('Error: browserTest.geminiApiKey not found in project-settings.json.');
+        console.log('Add "browserTest": { "geminiApiKey": "..." } to .requirements/project-settings.json');
+        process.exit(1);
+    }
+    // 4. Load requirements
+    const { flattened } = await loadAllRequirements(projectInfo.rootPath);
+    if (flattened.length === 0) {
+        console.error('Error: No requirements found in .requirements/');
+        process.exit(1);
+    }
+    // 5. Find the requirement tree
+    const requirementTree = getRequirementTree(flattened, requirementKey);
+    if (requirementTree.length === 0) {
+        console.error(`Error: Requirement "${requirementKey}" not found.`);
+        process.exit(1);
+    }
+    // 6. Format each requirement as an assertion
+    const assertions = requirementTree.map((req) => formatRequirement(req));
+    // 7. Build environment with injected secrets
+    const env = { ...process.env };
+    env.GEMINI_API_KEY = geminiApiKey;
+    if (settings?.browserTest?.vercelBypassSecret) {
+        env.VERCEL_AUTOMATION_BYPASS_SECRET = settings.browserTest.vercelBypassSecret;
+    }
+    if (settings?.browserTest?.browserbaseApiKey) {
+        env.BROWSERBASE_API_KEY = settings.browserTest.browserbaseApiKey;
+    }
+    if (settings?.browserTest?.browserbaseProjectId) {
+        env.BROWSERBASE_PROJECT_ID = settings.browserTest.browserbaseProjectId;
+    }
+    // 8. Run browser-automation
+    if (!options.json) {
+        console.log(`Testing ${requirementKey} against ${targetURL}...\n`);
+    }
+    try {
+        const { stdout } = await execFileAsync('npx', ['@popoverai/browser-automation', 'test', targetURL, ...assertions], { env, maxBuffer: 10 * 1024 * 1024 });
+        // 9. Parse results
+        let results;
+        try {
+            results = JSON.parse(stdout.trim());
+        }
+        catch {
+            console.error('Error: Could not parse browser-automation output');
+            console.error(stdout);
+            process.exit(1);
+        }
+        // 10. Display results
+        if (options.json) {
+            outputJson(requirementTree, results);
+        }
+        else {
+            displayResults(requirementTree, results);
+        }
+        // 11. Exit with appropriate code
+        const failedCount = results.filter((r) => r.status !== 'passed').length;
+        if (failedCount > 0) {
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        const error = err;
+        // browser-automation returns exit code 1 on failure, but still outputs JSON
+        if (error.stdout) {
+            try {
+                const results = JSON.parse(error.stdout.trim());
+                if (options.json) {
+                    outputJson(requirementTree, results);
+                }
+                else {
+                    displayResults(requirementTree, results);
+                }
+                process.exit(1);
+            }
+            catch {
+                // Not JSON, show raw output
+                console.error('browser-automation error:');
+                if (error.stdout)
+                    console.error(error.stdout);
+                if (error.stderr)
+                    console.error(error.stderr);
+                process.exit(1);
+            }
+        }
+        else {
+            console.error(`Error running browser-automation: ${error.message}`);
+            if (error.stderr)
+                console.error(error.stderr);
+            process.exit(1);
+        }
+    }
+}
+function displayResults(requirements, results) {
+    let passedCount = 0;
+    let failedCount = 0;
+    for (let i = 0; i < requirements.length; i++) {
+        const req = requirements[i];
+        const result = results[i];
+        if (!result) {
+            console.log(`  ? ${req.id}: No result`);
+            failedCount++;
+            continue;
+        }
+        const indent = '  '.repeat(req.path.length);
+        const label = req.label ? ` (${req.label})` : '';
+        const icon = result.status === 'passed' ? '\u2713' : '\u2717';
+        console.log(`${indent}${icon} ${req.id}${label}: ${req.content}`);
+        if (result.status !== 'passed' && result.notes) {
+            console.log(`${indent}  \u2192 ${result.notes}`);
+        }
+        if (result.status === 'passed') {
+            passedCount++;
+        }
+        else {
+            failedCount++;
+        }
+    }
+    console.log();
+    if (failedCount === 0) {
+        console.log(`${passedCount}/${requirements.length} passed`);
+    }
+    else {
+        console.log(`${passedCount}/${requirements.length} passed, ${failedCount} failed`);
+    }
+}
+function outputJson(requirements, results) {
+    const combined = requirements.map((req, i) => ({
+        id: req.id,
+        label: req.label || null,
+        content: req.content,
+        status: results[i]?.status || 'blocked',
+        notes: results[i]?.notes || null,
+    }));
+    console.log(JSON.stringify(combined, null, 2));
+}
+//# sourceMappingURL=browsertest.js.map

package/dist/utils/project-settings.d.ts

@@ -1,9 +1,20 @@
+/**
+ * Browser test configuration
+ */
+export interface BrowserTestSettings {
+    geminiApiKey?: string;
+    vercelBypassSecret?: string;
+    browserbaseApiKey?: string;
+    browserbaseProjectId?: string;
+}
 /**
  * Project credentials stored in project-settings.json
  */
 export interface ProjectSettings {
     projectId: string;
     projectSecret: string;
+    defaultURL?: string;
+    browserTest?: BrowserTestSettings;
 }
 /**
  * Project status indicating whether it's connected to cloud

package/dist/utils/project-settings.js

@@ -68,10 +68,32 @@ export function readProjectSettings(projectRoot) {
         typeof parsed.projectSecret !== 'string') {
         throw new Error('project-settings.json is invalid: missing projectId or projectSecret');
     }
-    return {
-        projectId: parsed.projectId,
-        projectSecret: parsed.projectSecret,
+    const record = parsed;
+    const settings = {
+        projectId: record.projectId,
+        projectSecret: record.projectSecret,
     };
+    // Optional fields
+    if (typeof record.defaultURL === 'string') {
+        settings.defaultURL = record.defaultURL;
+    }
+    if (typeof record.browserTest === 'object' && record.browserTest !== null) {
+        const bt = record.browserTest;
+        settings.browserTest = {};
+        if (typeof bt.geminiApiKey === 'string') {
+            settings.browserTest.geminiApiKey = bt.geminiApiKey;
+        }
+        if (typeof bt.vercelBypassSecret === 'string') {
+            settings.browserTest.vercelBypassSecret = bt.vercelBypassSecret;
+        }
+        if (typeof bt.browserbaseApiKey === 'string') {
+            settings.browserTest.browserbaseApiKey = bt.browserbaseApiKey;
+        }
+        if (typeof bt.browserbaseProjectId === 'string') {
+            settings.browserTest.browserbaseProjectId = bt.browserbaseProjectId;
+        }
+    }
+    return settings;
 }
 /**
  * Write project settings to .requirements/project-settings.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {