> For the complete documentation index, see [llms.txt](https://docs.decisionrules.io/doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decisionrules.io/doc/api/rule-testing-api.md).

# Rule Testing API

The Rule Testing API runs your saved tests and returns their results.

## Authentication

Every request needs a [**Solver API key**](/doc/api/api-keys/solver-api-keys.md) in the `Authorization` header:

```javascript
Authorization: Bearer <YOUR_SOLVER_API_KEY>
```

## Start a Test Run

> Starts a new test run job for the specified test suites or individual tests.  You must provide either an array of \`testSuiteIds\`, an array of \`testIds\`, or both.

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"servers":[{"url":"https://api.decisionrules.io/testRun"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}},"schemas":{"JobState":{"type":"string","enum":["WAITING","RUNNING","COMPLETED","CANCELING","CANCELED","ERROR"]}}},"paths":{"/start":{"post":{"summary":"Start a Test Run","description":"Starts a new test run job for the specified test suites or individual tests.  You must provide either an array of `testSuiteIds`, an array of `testIds`, or both.","operationId":"startTestRun","parameters":[{"name":"x-correlation-id","in":"header","required":false,"description":"A custom correlation ID to track the job execution. If not provided, a GUID will be automatically generated.","schema":{"type":"string"}}],"requestBody":{"description":"Input data specifying which test suites or test cases to run.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"testSuiteIds":{"type":"array","items":{"type":"string"},"description":"A list of Test Suite IDs to be executed."},"testIds":{"type":"array","items":{"type":"string"},"description":"A list of individual Test IDs to be executed."},"solverVersion":{"type":"string","enum":["v1","v2"],"description":"Solver version for this test run. Defaults to v1 when omitted."}}}}}},"responses":{"200":{"description":"The test run job has been successfully created and queued.","content":{"application/json":{"schema":{"type":"object","properties":{"testRunId":{"type":"string","description":"The ID of the newly created test run job."},"status":{"$ref":"#/components/schemas/JobState","description":"Initial status of the test run job (e.g., WAITING)."}}}}},"headers":{"X-Solver-Version":{"description":"Solver version the test run uses.","schema":{"type":"string","enum":["v1","v2"]}},"X-Solver-Engine":{"description":"Name of the solver engine the test run uses: `aero` (v2) or `gaia` (v1).","schema":{"type":"string"}}}},"400":{"description":"Business error. Missing parameters or rule resolution failed."},"401":{"description":"Unauthorized. Invalid or missing API key."}}}}}}
```

## Get Test Run Job

> Retrieves test run job details for a specific test run, including its overall execution state and timing context. The job must belong to the requesting space.

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"servers":[{"url":"https://api.decisionrules.io/testRun"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}},"schemas":{"Job":{"type":"object","properties":{"jobId":{"type":"string"},"correlationId":{"type":"string"},"inputData":{"type":"object","additionalProperties":true},"output":{"type":"object","additionalProperties":true,"nullable":true},"status":{"$ref":"#/components/schemas/JobStatus"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"claimedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time","nullable":true},"solverVersion":{"type":"string","enum":["v1","v2"],"description":"Solver version the test run uses."}}},"JobStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/JobState"},"code":{"type":"string"},"message":{"type":"string","description":"A human-readable message for the status."}}},"JobState":{"type":"string","enum":["WAITING","RUNNING","COMPLETED","CANCELING","CANCELED","ERROR"]}}},"paths":{"/{testRunId}":{"get":{"summary":"Get Test Run Job","description":"Retrieves test run job details for a specific test run, including its overall execution state and timing context. The job must belong to the requesting space.","operationId":"getJobsDetail","parameters":[{"name":"testRunId","in":"path","required":true,"description":"The ID of the test run job to retrieve details for.","schema":{"type":"string"}}],"responses":{"200":{"description":"Job details retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Business error."},"401":{"description":"Unauthorized. Invalid or missing API key."}}}}}}
```

## Get Test Run Results Detail

> Retrieves detailed information about a specific test run execution, including the evaluation status of individual tests and test suites.

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"servers":[{"url":"https://api.decisionrules.io/testRun"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"ApiKey"}},"schemas":{"TestRunRule":{"type":"object","required":["testSuiteRuns"],"properties":{"baseId":{"type":"string"},"baseType":{"$ref":"#/components/schemas/BaseType"},"status":{"$ref":"#/components/schemas/BaseStatus"},"ruleName":{"type":"string"},"ruleAlias":{"type":"string"},"ruleVersion":{"type":"number"},"testSuiteRuns":{"type":"array","items":{"$ref":"#/components/schemas/TestSuiteRun"},"description":"Array of test suites executed under this rule."}}},"BaseType":{"type":"string","enum":["decision-table","complex-rule","composition","decision-tree","workflow","integration-flow","lookup-table","ai-rule"]},"BaseStatus":{"type":"string","enum":["published","pending"]},"TestSuiteRun":{"type":"object","required":["testSuiteId","status","tests","jobId","createdAt"],"properties":{"id":{"type":"string"},"userId":{"type":"string"},"spaceId":{"type":"string"},"ruleAlias":{"type":"string"},"ruleVersion":{"type":"number"},"name":{"type":"string"},"testSuiteId":{"type":"string"},"status":{"$ref":"#/components/schemas/TestSuiteRunStatus"},"tests":{"type":"array","items":{"$ref":"#/components/schemas/TestExecution"}},"jobId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"claimedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"}}},"TestSuiteRunStatus":{"type":"string","enum":["WAITING","RUNNING","COMPLETED","CANCELED","ERROR"]},"TestExecution":{"type":"object","required":["testId","name","strategy","input","expectedOutput","ignoredOutputs"],"properties":{"id":{"type":"string"},"testId":{"type":"string"},"name":{"type":"string"},"strategy":{"$ref":"#/components/schemas/SolverStrategyEnum"},"input":{"description":"Input payload for the test execution."},"expectedOutput":{"description":"The expected output."},"ignoredOutputs":{"type":"array","items":{"type":"string"},"description":"Array of object paths to ignore (e.g., \"object.property\")"},"sortedInputHash":{"type":"string"},"lastRunAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"resultStatus":{"$ref":"#/components/schemas/TestResultStatus"},"result":{"description":"Actual execution result payload."},"error":{"description":"Error details if the test failed or errored."}}},"SolverStrategyEnum":{"type":"string","enum":["STANDARD","ARRAY","FIRST_MATCH","EVALUATE_ALL"]},"TestResultStatus":{"type":"string","enum":["PASSED","FAILED","ERROR"]}}},"paths":{"/detail/{testRunId}":{"get":{"summary":"Get Test Run Results Detail","description":"Retrieves detailed information about a specific test run execution, including the evaluation status of individual tests and test suites.","operationId":"getTestRunDetail","parameters":[{"name":"testRunId","in":"path","required":true,"description":"The Test Run ID to retrieve results for.","schema":{"type":"string"}}],"responses":{"200":{"description":"Test run details retrieved successfully. Returns an array of evaluated rules, grouped by test suites and their nested test executions.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TestRunRule"}}}}},"400":{"description":"Business error."},"401":{"description":"Unauthorized. Invalid or missing API key."}}}}}}
```

## The TestRunRule object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"TestRunRule":{"type":"object","required":["testSuiteRuns"],"properties":{"baseId":{"type":"string"},"baseType":{"$ref":"#/components/schemas/BaseType"},"status":{"$ref":"#/components/schemas/BaseStatus"},"ruleName":{"type":"string"},"ruleAlias":{"type":"string"},"ruleVersion":{"type":"number"},"testSuiteRuns":{"type":"array","items":{"$ref":"#/components/schemas/TestSuiteRun"},"description":"Array of test suites executed under this rule."}}},"BaseType":{"type":"string","enum":["decision-table","complex-rule","composition","decision-tree","workflow","integration-flow","lookup-table","ai-rule"]},"BaseStatus":{"type":"string","enum":["published","pending"]},"TestSuiteRun":{"type":"object","required":["testSuiteId","status","tests","jobId","createdAt"],"properties":{"id":{"type":"string"},"userId":{"type":"string"},"spaceId":{"type":"string"},"ruleAlias":{"type":"string"},"ruleVersion":{"type":"number"},"name":{"type":"string"},"testSuiteId":{"type":"string"},"status":{"$ref":"#/components/schemas/TestSuiteRunStatus"},"tests":{"type":"array","items":{"$ref":"#/components/schemas/TestExecution"}},"jobId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"claimedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"}}},"TestSuiteRunStatus":{"type":"string","enum":["WAITING","RUNNING","COMPLETED","CANCELED","ERROR"]},"TestExecution":{"type":"object","required":["testId","name","strategy","input","expectedOutput","ignoredOutputs"],"properties":{"id":{"type":"string"},"testId":{"type":"string"},"name":{"type":"string"},"strategy":{"$ref":"#/components/schemas/SolverStrategyEnum"},"input":{"description":"Input payload for the test execution."},"expectedOutput":{"description":"The expected output."},"ignoredOutputs":{"type":"array","items":{"type":"string"},"description":"Array of object paths to ignore (e.g., \"object.property\")"},"sortedInputHash":{"type":"string"},"lastRunAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"resultStatus":{"$ref":"#/components/schemas/TestResultStatus"},"result":{"description":"Actual execution result payload."},"error":{"description":"Error details if the test failed or errored."}}},"SolverStrategyEnum":{"type":"string","enum":["STANDARD","ARRAY","FIRST_MATCH","EVALUATE_ALL"]},"TestResultStatus":{"type":"string","enum":["PASSED","FAILED","ERROR"]}}}}
```

## The TestSuiteRun object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"TestSuiteRun":{"type":"object","required":["testSuiteId","status","tests","jobId","createdAt"],"properties":{"id":{"type":"string"},"userId":{"type":"string"},"spaceId":{"type":"string"},"ruleAlias":{"type":"string"},"ruleVersion":{"type":"number"},"name":{"type":"string"},"testSuiteId":{"type":"string"},"status":{"$ref":"#/components/schemas/TestSuiteRunStatus"},"tests":{"type":"array","items":{"$ref":"#/components/schemas/TestExecution"}},"jobId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"claimedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"}}},"TestSuiteRunStatus":{"type":"string","enum":["WAITING","RUNNING","COMPLETED","CANCELED","ERROR"]},"TestExecution":{"type":"object","required":["testId","name","strategy","input","expectedOutput","ignoredOutputs"],"properties":{"id":{"type":"string"},"testId":{"type":"string"},"name":{"type":"string"},"strategy":{"$ref":"#/components/schemas/SolverStrategyEnum"},"input":{"description":"Input payload for the test execution."},"expectedOutput":{"description":"The expected output."},"ignoredOutputs":{"type":"array","items":{"type":"string"},"description":"Array of object paths to ignore (e.g., \"object.property\")"},"sortedInputHash":{"type":"string"},"lastRunAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"resultStatus":{"$ref":"#/components/schemas/TestResultStatus"},"result":{"description":"Actual execution result payload."},"error":{"description":"Error details if the test failed or errored."}}},"SolverStrategyEnum":{"type":"string","enum":["STANDARD","ARRAY","FIRST_MATCH","EVALUATE_ALL"]},"TestResultStatus":{"type":"string","enum":["PASSED","FAILED","ERROR"]}}}}
```

## The TestExecution object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"TestExecution":{"type":"object","required":["testId","name","strategy","input","expectedOutput","ignoredOutputs"],"properties":{"id":{"type":"string"},"testId":{"type":"string"},"name":{"type":"string"},"strategy":{"$ref":"#/components/schemas/SolverStrategyEnum"},"input":{"description":"Input payload for the test execution."},"expectedOutput":{"description":"The expected output."},"ignoredOutputs":{"type":"array","items":{"type":"string"},"description":"Array of object paths to ignore (e.g., \"object.property\")"},"sortedInputHash":{"type":"string"},"lastRunAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"resultStatus":{"$ref":"#/components/schemas/TestResultStatus"},"result":{"description":"Actual execution result payload."},"error":{"description":"Error details if the test failed or errored."}}},"SolverStrategyEnum":{"type":"string","enum":["STANDARD","ARRAY","FIRST_MATCH","EVALUATE_ALL"]},"TestResultStatus":{"type":"string","enum":["PASSED","FAILED","ERROR"]}}}}
```

## The BaseType object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"BaseType":{"type":"string","enum":["decision-table","complex-rule","composition","decision-tree","workflow","integration-flow","lookup-table","ai-rule"]}}}}
```

## The BaseStatus object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"BaseStatus":{"type":"string","enum":["published","pending"]}}}}
```

## The TestSuiteRunStatus object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"TestSuiteRunStatus":{"type":"string","enum":["WAITING","RUNNING","COMPLETED","CANCELED","ERROR"]}}}}
```

## The TestResultStatus object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"TestResultStatus":{"type":"string","enum":["PASSED","FAILED","ERROR"]}}}}
```

## The SolverStrategyEnum object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"SolverStrategyEnum":{"type":"string","enum":["STANDARD","ARRAY","FIRST_MATCH","EVALUATE_ALL"]}}}}
```

## The JobState object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"JobState":{"type":"string","enum":["WAITING","RUNNING","COMPLETED","CANCELING","CANCELED","ERROR"]}}}}
```

## The JobStatus object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"JobStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/JobState"},"code":{"type":"string"},"message":{"type":"string","description":"A human-readable message for the status."}}},"JobState":{"type":"string","enum":["WAITING","RUNNING","COMPLETED","CANCELING","CANCELED","ERROR"]}}}}
```

## The Job object

```json
{"openapi":"3.0.0","info":{"title":"Rule Testing API","version":"1.0.0"},"components":{"schemas":{"Job":{"type":"object","properties":{"jobId":{"type":"string"},"correlationId":{"type":"string"},"inputData":{"type":"object","additionalProperties":true},"output":{"type":"object","additionalProperties":true,"nullable":true},"status":{"$ref":"#/components/schemas/JobStatus"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"claimedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time","nullable":true},"solverVersion":{"type":"string","enum":["v1","v2"],"description":"Solver version the test run uses."}}},"JobStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/JobState"},"code":{"type":"string"},"message":{"type":"string","description":"A human-readable message for the status."}}},"JobState":{"type":"string","enum":["WAITING","RUNNING","COMPLETED","CANCELING","CANCELED","ERROR"]}}}}
```

## **Solver version**

Each test run uses one solver version. Set it with `solverVersion` in the request body:

```json
{
  "testSuiteIds": ["<TEST_SUITE_ID>"],
  "solverVersion": "v2"
}
```

It takes `v1` or `v2`. If you leave it out, the tests run on `v1`. The test run detail shows the version it used, in `solverVersion`.

The same tests can run on either version. See [Rule Solver API Migration](/doc/api/rule-solver-api/solver-version-migration.md).

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decisionrules.io/doc/api/rule-testing-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.