> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veecle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# test

> Run firmware checks on a virtual board and read back what passed, what failed, and the captured output.

<Info>
  This page describes what your AI agent can do with Chiplab.
  You don't need to call anything yourself, just ask your agent to test your firmware and it takes care of the rest.
  This is a reference for the curious, not a set of instructions for you to follow.
</Info>

`test` runs your firmware's checks on a virtual instance of a supported board and returns the outcome to your agent.
The board is one of the models on [Hardware](/hardware/boards), and the captured output is the UART you asked for, the same way as a [run](/tools/run).

Use it when the question is whether the firmware behaves: a unit check, an integration check, or a known-good line in the UART log.
A [build](/tools/build) produces the binary. A test tells you what that binary did on the chip.

Your agent discovers the current parameters when it connects.
Every session still starts with [`ask`](/tools/ask), which carries the live tool list and the board-specific gotchas.

## Reading the outcome

Once Chiplab has accepted the test, your agent waits and then downloads the artifacts, using the same job calls as a run.

`wait_for_job` takes the job id Chiplab returned and an optional `timeout`.
It responds with:

<ResponseField name="status" type="string">
  `running`, `succeeded`, or `failed`.
</ResponseField>

<ResponseField name="input" type="object">
  The firmware and board the test was started with.
</ResponseField>

<ResponseField name="result" type="object">
  Present when `status` is `succeeded`. Includes an `artifacts` list. `stdout` is the captured UART output.
</ResponseField>

<ResponseField name="error" type="string">
  Present when `status` is `failed`. What went wrong.
</ResponseField>

A response with `status: "running"` and `timed_out: true` means the test is still going.
Call `wait_for_job` again to keep waiting.

`issue_download_ticket` takes that job id and an `artifact_name` from the `artifacts` list.
The response is a presigned `download_url`.
A `GET` of that URL returns the artifact bytes, with no auth header.

The public examples treat a successful test as `Hello world!` in that UART capture.
Your agent should request the peripheral the firmware writes, or `stdout` is empty.
The STM32F4 Discovery examples write `usart2`.