Kovar

Security testing assertions + AI-powered test recording for Playwright. Add security checks to your E2E tests without being a security expert, and record browser sessions that generate production-grade Page Object Model tests.

Install

npm install -D @orlalabs/kovar

Quick Start

Replace your Playwright import with Kovar -- everything else stays the same:

import { test, expect } from "@orlalabs/kovar"; // was: '@playwright/test'

test("login page has secure headers", async ({ page }) => {
  const response = await page.goto("/login");
  await expect(response!).toHaveSecureHeaders();
});

Features

Security Checks

• HTTP Headers -- 12 OWASP-aligned header checks with CSP validation
• Cookie Flags -- session cookie security (Secure, HttpOnly, SameSite, prefix validation)
• Reflected XSS -- 40 polyglot payloads with API-first and DOM testing
• CSRF Protection -- verifies state-changing endpoints reject tokenless requests
• CORS Configuration -- tests for origin reflection and wildcard misconfigurations
• Authentication -- verifies protected endpoints reject unauthenticated requests
• Accessibility -- 10 WCAG 2.1 rules covering images, forms, landmarks, headings

Fixtures & API

• Security Fixture -- programmatic access to all checks with assert() and check() modes
• Full Audit -- run all checks at once and get a structured report
• Standalone API -- use check functions outside the Playwright test runner

Remediation & Compliance

• Auto-Remediation -- framework-specific fix suggestions (Express, Fastify, Next.js, Koa, Hono)
• OWASP ASVS -- map findings to ASVS 4.0.3 requirements
• PCI-DSS -- map findings to PCI-DSS 4.0 requirements

CI/CD

• GitHub Action -- run security checks in CI with PR comments
• Baseline Tracking -- detect regressions across PRs
• Reporter -- Playwright reporter with security score cards

AI Recorder

• Record browser sessions -- capture interactions and generate Page Object Model tests
• Self-Healing -- auto-fix test failures after recording
• Codebase Awareness -- source-verified locators for higher test stability

MCP Server

Local-first MCP server for recording, asserting, and replaying agent runs. Runs go to ~/.kovar/runs.db (no cloud, no auth — override with KOVAR_DB_PATH). Tools exposed: record_run, assert_tool_called, assert_no_drift, assert_cost_under, replay_run, record_canonical, get_run, list_runs.

Add to your MCP client config (Claude Code: ~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "kovar": {
      "command": "npx",
      "args": ["-y", "@orlalabs/kovar", "mcp"]
    }
  }
}

Then in a session, ask the agent to record what it did and assert against it:

You: Solve the bug, then call record_run with run_id="fix-1" capturing every tool
     you used (tool_name, args, timestamp).
You: Now call assert_tool_called(run_id="fix-1", tool_name="Read", args={path:
     "src/auth.ts"}).
You: If that passed, save it as a canonical: record_canonical(name="auth-fix",
     run_ids=["fix-1"]).

Or embed it in your own test suite via the public API:

import { Store, HANDLERS } from "@orlalabs/kovar/mcp";

const store = new Store({ dbPath: ":memory:" });
HANDLERS.record_run(store, {
  agent_id: "demo",
  run_id: "r1",
  events: [
    { tool_name: "Read", args: { path: "src/auth.ts" }, timestamp: Date.now() },
    { tool_name: "Edit", args: { path: "src/auth.ts" }, timestamp: Date.now() },
  ],
});
const result = HANDLERS.assert_tool_called(store, { run_id: "r1", tool_name: "Read" });
// { passed: true, actual_count: 1, ... }

Documentation

Full documentation is available at kovar.orlalabs.com.

License

Apache 2.0