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

# Comparing versions

> Run the same Test Cases on several versions of a Canvas, read the difference, catch regressions and decide what to publish

A Test Case is only useful the second time you run it. The first run tells you what the Canvas does; the second, on a changed prompt or a new model, tells you whether the change helped, hurt, or broke something that used to work. Tela keeps one run per Test Case per version, and your examples and rules travel with the Test Case, so comparing two versions is a matter of running the suite on both and reading the same metrics twice.

The scenario on this page: version 4 of the invoice Canvas is in Production. You rewrote the prompt to handle scanned invoices, which created version 5. Before publishing, you want to know that version 5 reads the scan and still gets the clean invoice and the two-currency one right.

## One run per version

Every run is attached to the version that produced it. The **Test** experience shows the runs, statuses and metrics of the version you are viewing, and nothing else:

* Open the Canvas and you are viewing the version you are editing, marked **Current** in the **Version History**. After an edit, this is the new version, and every Test Case shows **Pending Run** again.
* Open the **Version History** from the version button next to **Publish** and click **View** on an older version to see its runs and its **Accuracy Score**. The **Version** column of the table tells you which version a Test Case was first run on.
* Click **View** on the **Current** version, or **Restore** an older one, to come back.

Reviews, Expected Answers, Wrong Answers and rules are properties of the Test Case, not of a version. Whatever you taught the suite on version 4 is applied to the runs of version 5 automatically.

![Version History of the invoice Canvas with version 4 marked production and version 5 marked Current, the View button visible on version 4](https://mintcdn.com/meistrari/M2w7BduKZAFA1Sbx/images/test-cases/version-history.png?fit=max\&auto=format\&n=M2w7BduKZAFA1Sbx\&q=85\&s=efcb35f3623c24f8c5f1c4ed97b31e25)

## Running the suite on a new version

**1. Finish reviewing the old version first**

Before changing the prompt, make sure the suite is **Completed** on version 4 and the **Accuracy Score** reads what you expect. This is your baseline. Unreviewed attributes on the old version cannot be compared with anything.

**2. Change the prompt in Craft**

Rewrite the instructions for scanned documents. Tela creates version 5 as the version you are editing.

**3. Run All in Test**

Back in **Test**, every Test Case is **Pending Run** on version 5. Click **Run All**. Attributes that match your examples or pass your rules come back **AUTO-REVIEWED**; the others wait for you.

**4. Review what is left**

Filter by **Pending Review**, open each Test Case and give a verdict to the attributes that changed. Typically these are exactly the attributes the new prompt affected.

**5. Read the two versions side by side**

Note the **Accuracy Score**, **Reviewed** and **Attributes** of version 5, then **View** version 4 in the **Version History** and compare. Do the same per Test Case: the **Score** column and the red cells of the row show where each version went wrong.

Through the API, the same loop is [`POST /test-case/run-all`](https://docs.tela.com/api-reference/test-case/post-test-case-run-all) with the `promptVersionId` of each version, then [`GET /test-case`](https://docs.tela.com/api-reference/test-case/get) with `promptVersionIds` to read the runs. Version IDs come from [the version history of the Canvas](https://docs.tela.com/api-reference/prompt-version/get-prompt-version-history.md).

```sh cURL theme={null}
# Run the whole suite on version 5
curl -X POST https://api.tela.com/test-case/run-all \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -d '{ "promptVersionId": "VERSION_5_ID" }'

# Read the runs of version 5 for every Test Case of the Canvas (repeat with VERSION_4_ID for the baseline)
curl "https://api.tela.com/test-case?promptId=CANVAS_ID&promptVersionIds=VERSION_5_ID&includeGenerations=true" \
    -H "Authorization: Bearer $TELA_API_KEY"
```

## Reading the difference

Three outcomes matter, and the table shows each of them differently:

| What you see on version 5 | Meaning | What to do |
| - | - | - |
| The scanned invoice goes from a red `total_amount` to **AUTO-REVIEWED** Good | The change did what it was meant to do | Nothing |
| The two-currency invoice, green on version 4, now shows `total_amount` in red (*Does not match expected answers*) | A regression: the new prompt broke a case that worked | Fix the prompt, run again on the next version |
| A Test Case that was **Completed** on version 4 is **Pending Review** on version 5 with a value you have never seen | A new behaviour, neither known good nor known bad | Review it; your verdict becomes an example for the next version |

Automatic verdicts are what make regressions visible without rereading every document. A Test Case with Expected Answers on all four attributes needs no human review on a new version unless a value changed, and a changed value that matches no Expected Answer is marked **Bad** immediately. The more you review on one version, the less you need to review on the next.

> [!WARNING]
>
> Switching models is a change like any other. A faster or cheaper model can score the same on the clean invoice and lose the scanned one. Run the full suite, not the one case you were looking at, before publishing a model change.

## Deciding what to publish

Publish version 5 when:

* its **Accuracy Score** is at least that of version 4, with the same or better **Attributes** coverage;
* no Test Case went from green to red, or every one that did was reviewed and the new value accepted on purpose;
* the Test Cases labelled for the behaviour you changed (for example `scanned`) are green.

Then click **Publish**, choose the **Publish target** and confirm. Apps and API calls on that environment pick up version 5 immediately. If you want a last check with real traffic first, publish to a `staging` environment and call it with `environment_name`, as described in [Versions and environments](https://docs.tela.com/en/completion-api/versions-and-environments.md).

If version 5 is worse, you have two options: keep editing (each edit is a new version, run the suite again), or open the **Version History** and **Restore** version 4 as the version you edit. See [Going back to a previous version](https://docs.tela.com/en/craft/publishing.md#going-back-to-a-previous-version).

> [!TIP]
>
> Label the Test Cases that cover a behaviour you are about to change (`scanned`, `multi-currency`) before you change it. **Run Filtered** on that label gives a fast answer while you iterate; **Run All** before publishing gives the full one.

## Keeping the suite alive

A suite that stops growing stops catching regressions. Two habits keep it useful:

* Every time your team corrects a task in the Workstation, turn it into a Test Case. Each one arrives already reviewed, with the correction as an Expected Answer and the mistake as a Wrong Answer, so it costs nothing to review and it encodes a mistake the Canvas has actually made.
* When a Test Case fails on a new version for a good reason (the document changed, the expected output was wrong), fix the Test Case rather than ignoring the red: update the Expected Answer in the **Examples** tab, or **Edit Inputs**.

### In Workflows

Workflow versions work the same way: one run per Test Case per version, metrics per version, **Version History** to switch. Because a Workflow run executes every step, compare the step whose output changed, not only the final result. See [Running, testing and publishing](https://docs.tela.com/en/workflow/running-testing-and-publishing.md#test-cases).

### In Agents

Agents keep one run per test case per version too, and each test case has a **Run history** that lists its runs across versions with the attributes that changed since the last run. Opening a test case while viewing an older version shows **No execution for this version**. See [Running them all](https://docs.tela.com/en/agent/testing.md#running-them-all).

> [!NOTE]
>
> There is no side-by-side comparison view. The comparison described on this page is done by switching versions in the **Version History** and reading the metrics of each.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.