Skip to main content
Glama
README.md
# Horus

<img src="docs/assets/horus-logo.png" alt="horus logo" width="100%" />

[简体中文](README.zh-CN.md) · [Setup](docs/usage.md) · [Architecture](docs/architecture.md) · [Roadmap](docs/roadmap.md)

**Know whether workflows succeed, how they perform under load, and where they fail.**

Horus is a **domain-agnostic automated testing platform driven by AI agents**.
Tools such as Codex and Claude Code use a Skill to understand the business,
design tests, and investigate failures. Horus provides end-to-end execution,
result verification, and reporting through MCP.

Each project defines its workflows, data, and pass criteria. Horus reuses the
same testing capabilities across projects. It runs locally, uses your existing
agent and model, and keeps plans and execution records in your workspace.

## What you get

A report organized by **complete business workflows**, with conclusions first
and problem details available when needed.

| Your question | What the report tells you |
| --- | --- |
| **Did the workflow succeed?** | Whether it completed with the expected state and data, with failures and unknown outcomes listed separately. |
| **How much concurrency can it handle?** | Actual load, workflow success rates, and the tested load levels that met your criteria. |
| **How long do users wait?** | Load journey duration and key action latency, including P95; functional tests retain individual request timings in the details. |
| **Where did it fail?** | The failed step, API method and path, observed error, and impact for the agent to investigate. |
| **What remains unresolved?** | Incomplete tests, uncertain outcomes, and cleanup issues. |

Successful API responses still require verification of the business outcome.
Load conclusions state the environment, data, duration, and pass criteria.
Passing one load level does not establish maximum capacity.

## How it works

- **You define the goal.** Provide requirements, expected outcomes, and API
  documentation, then confirm the scope and load.
- **The agent + Skill understand and orchestrate.** Map business dependencies,
  design scenarios, investigate failures, and decide the next testing actions.
- **Horus executes and verifies.** Run functional and load tests across APIs,
  services, identities, and asynchronous steps, managing data, runs, and evidence.

```mermaid
%%{init: {"theme":"base","htmlLabels":false,"themeVariables":{"fontFamily":"sans-serif","fontSize":"15px","lineColor":"#64748b"},"flowchart":{"curve":"basis","htmlLabels":false}}}%%
flowchart TB
    A["Describe the goal"] --> B["Agent designs<br/>You confirm"]
    B --> C["Horus executes and verifies<br/>Prepare · Test · Clean up"]
    C --> D["Business results"]
    D -.->|Problems found| E["Agent investigates<br/>and adjusts"]
    E -.->|Confirm changes| B
    D -.->|Replay approved scope| C
    classDef action fill:#eaf7f3,stroke:#4a8e7c,color:#164c40,stroke-width:1.5px;
    classDef agent fill:#f1edff,stroke:#8b79b8,color:#403366,stroke-width:1.5px;
    classDef result fill:#fff5df,stroke:#b78328,color:#62430e,stroke-width:1.5px;
    class A,C action;
    class B,E agent;
    class D result;
```

A background Worker runs independently of the chat connection; reconnect to
query the same run. Approved plans can be replayed and compared, while original
failure records remain intact.

## Quick start

Copy this into your coding agent:

```text
Follow https://github.com/xucailiang/horus/blob/master/docs/usage.md to install
horus, configure its MCP server and Skill in this coding tool, and verify the connection.
```

See the [setup guide](docs/usage.md) for manual installation, Codex / Claude Code
configuration, and other MCP clients.

Then give it your documentation and a testing goal:

```text
Test <service URL> with Horus. The API documentation is at <URL or local file path>.
The business goal is <what the user needs to do>, with <expected final state or data>.
Design end-to-end functional and load tests for normal and important failure paths.
Show the scenarios, pass criteria, load, and data handling scope. Wait for my confirmation.
Then test, clean up, and report workflow outcomes, actual load, timings, and failed APIs.
```

Confirm the plan in the conversation before execution. Changes to scope,
expectations, or load need fresh confirmation. Unknown outcomes remain explicit;
weaker assertions cannot turn a failure into a pass.

## Current scope

**Alpha · macOS / Linux · Python 3.12.** The current focus is end-to-end testing
through HTTP/REST APIs with JSON, regardless of the backend's programming language.

Multiple identities, cross-service flows, asynchronous polling, fixed-user and
arrival-rate workloads, cleanup recovery, and regression comparison are supported.
Browser UI testing, general file uploads, distributed load generation, and
hour-scale stability tests are not yet covered. The complete lifecycle on
independent real projects still needs validation. See the
[current limits](docs/architecture.md#current-limits) and [roadmap](docs/roadmap.md).

## Documentation

- [Setup, configuration, and CLI usage](docs/usage.md)
- [Architecture and limits](docs/architecture.md)
- [Product direction and roadmap](docs/roadmap.md)

## Contributing

Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
for development setup and local checks.

## License

[MIT](LICENSE)