oracle

Oracle 🧠

Oracle is an AI-powered test automation agent that transforms natural language requirements into high-quality, framework-aware test code.

🚀 Features

• Intent Classification: Automatically detects if you need E2E, API, Unit, or Performance tests.
• Framework Recommendation: Suggests the best-in-class tool (Playwright, Vitest, Pytest, k6) based on your needs.
• Code Generation: Produces production-ready test scripts following industry best practices.
• CLI-First: Simple terminal interface for seamless developer workflow.

🛠 Installation

pipx (recommended)

pipx install git+https://github.com/bri-stevenski/oracle-test-ai-agent@v0.2.0

This installs the oracle binary globally without polluting your project virtualenv. Upgrade by re-running with @<new-tag>.

From source

git clone https://github.com/bri-stevenski/oracle-test-ai-agent.git
cd oracle-test-ai-agent
pip install -e .

Claude Code plugin

Oracle ships as a Claude Code plugin with four MVP personas — oracle-test-author, oracle-test-reviewer, oracle-framework-advisor, and oracle-flake-hunter — plus the harness MCP server. Add it as a local marketplace:

/plugin marketplace add https://github.com/bri-stevenski/oracle-test-ai-agent
/plugin install oracle@oracle

Or, if you've already cloned the repo:

/plugin marketplace add /path/to/oracle-test-ai-agent
/plugin install oracle@oracle

Note: the plugin shells out to the oracle CLI for code generation, so install the Python package first (above) and set OPENAI_API_KEY before invoking the test-author persona.

📖 Usage

Generate Tests

To generate a test, simply provide a prompt. Oracle will classify the intent, recommend a framework, and generate the code.

oracle generate "Create a playwright test for the login flow on https://example.com"

Recommendation Only (Draft Mode)

If you want to see Oracle's reasoning without calling the LLM (and without needing an API key), use the --recommend-only flag:

oracle generate "I need a load test for my checkout API" --recommend-only

Version Info

oracle version

⚙️ Configuration

Oracle defaults to Claude (Anthropic). To use the generation features, set your API key:

export ANTHROPIC_API_KEY='your-anthropic-api-key'

Other providers (gemini, openai, mock) are available via the ORACLE_LLM_PROVIDER environment variable. See docs/wiki/LLM-Providers-and-Configuration.md for the full provider matrix and required env vars.

🏗 Architecture

Oracle follows a modular pipeline: User Prompt → Classifier → Recommender → Orchestrator → LLM → Generated Test

Generated by Oracle — The future of autonomous test engineering.