Cognita

⚠️ Early Development — Cognita is under active development. Expect breaking changes until we reach v1.0.

AI-powered end-to-end testing. Explore your app, generate tests, and let an AI agent execute them in a real browser.

What is Cognita?

Cognita is an AI testing agent that can:

1. Explore your web application — automatically crawl pages, identify modules, features, and generate test ideas
2. Generate test files — pick a module and get a complete test file with AI-driven test cases
3. Execute tests — an AI agent drives a real browser (Playwright), interacts with elements, detects visual bugs, and reports results

The agent sees screenshots, understands the interactive element tree, and uses tools to click, type, navigate, and assert — just like a human QA tester would.

Installation

npm install cognita

You'll also need Playwright browsers:

npx playwright install chromium

Quick Start

1. Create a config file

Create cognita.config.ts in your project root:

import type { CognitaConfig } from "cognita";

const config: CognitaConfig = {
  baseUrl: "http://localhost:3000",
  testDir: "tests/qa",

  testUsers: [
    {
      name: "default",
      username: "[email protected]",
      password: "password123",
    },
  ],

  browser: {
    scope: "describe",
    headless: false,
  },

  model: "anthropic/claude-3.7-sonnet",
  timeout: 300_000,
  maxIterations: 50,
  debug: true,
};

export default config;

2. Set your API key

Cognita uses OpenRouter to access AI models. Set your API key:

export OPENROUTER_API_KEY=your-key-here

Or add it to a .env file in your project root.

3. Explore your app

Start your application, then run:

npx cognita explore

This will:

• Launch a browser
• Log in with your test user
• Crawl all pages
• Use AI to identify modules, features, and test ideas
• Output a cognita-map.json file

4. Generate tests

npx cognita generate

Select a module from the interactive picker and Cognita generates a test file.

5. Run tests

Add a test script to your package.json:

{
  "scripts": {
    "test:qa": "jest --config jest.qa.config.js"
  }
}

With a Jest config like:

module.exports = {
  testEnvironment: "node",
  transform: {
    "^.+\\.tsx?$": "@swc/jest",
  },
  testMatch: ["**/tests/qa/**/*.test.[jt]s?(x)"],
  testTimeout: 120000,
};

Then:

npm run test:qa

Writing Tests Manually

You can also write tests directly:

import { createSuite } from "cognita";
import config from "./cognita.config";

const suite = createSuite(config);

describe("Settings", () => {
  suite.setup();

  it(
    "should update the organization name",
    suite.test(
      "Navigate to Settings > Organization. Change the organization name to 'Test Org' and verify it saves."
    )
  );

  it(
    "should invite a new user",
    suite.test(
      "Navigate to Settings > Users. Click 'Add users', enter [email protected], and verify the invitation is sent.",
      { user: "admin" }
    )
  );
});

Configuration

| Option | Type | Default | Description | |---|---|---|---| | baseUrl | string | — | Required. Base URL of the application under test | | testDir | string | "tests/qa" | Directory where generated tests are written | | testUsers | TestUser[] | [] | Test users for authentication | | browser.scope | "describe" \| "it" | "describe" | Browser lifecycle scope | | browser.headless | boolean | true | Run browser in headless mode | | model | string | "anthropic/claude-3.7-sonnet" | OpenRouter model name | | modelInstance | LanguageModel | — | Custom AI SDK model instance | | timeout | number | 120_000 | Test timeout in milliseconds | | maxIterations | number | 50 | Maximum agent iterations per test | | debug | boolean | false | Enable debug logging | | cache | boolean | true | Enable run caching for replay optimization |

Browser Scope

• "describe" (default) — One browser shared across all tests in a describe block. A fresh page is created per test, but cookies/session persist. Best for speed.
• "it" — A completely fresh browser per test. Fully isolated but slower.

Custom Model

You can pass any AI SDK-compatible model instance:

import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });

const config: CognitaConfig = {
  baseUrl: "http://localhost:3000",
  modelInstance: openai("gpt-4o"),
};

Caching

Cognita caches test runs to speed up subsequent executions. When a cached run's screenshots match the current page state (≥99% pixel similarity), the agent replays cached actions instead of calling the AI model.

Cache is stored in .cognita-cache/ (add this to your .gitignore).

Disable caching per config:

const config: CognitaConfig = {
  cache: false,
};

CLI Reference

cognita explore     # Map your app into cognita-map.json
cognita generate    # Pick a module, generate test file
cognita --help      # Show help
cognita --version   # Show version

License

Elastic License 2.0 (ELv2) — free to use, modify, and distribute. You just can't offer it as a hosted/managed service.