> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Set Up a Test Run Checklist
> Attach a checklist to a test run so testers can track a set of checklist items (such as review or exit criteria) directly against the test run, with the same save and template mechanics used on work items.
export const LastReviewed = ({date}) => {
if (!date) return null;
const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
year: "numeric",
month: "long",
day: "numeric",
timeZone: "UTC"
});
return
Last reviewed on {formatted}
;
};
## Before you start
Nextedy CHECKLIST persists checklist data through a save mechanism that recognizes four target types: documents, test runs, plans, and work items. This guide covers the **test run** target. The examples below use `dod` as the checklist ID — replace it with your own.
**Verify in application**
The gathered context does not include a step-by-step KB article specifically for test run checklist setup (unlike the dedicated articles that exist for work items and documents). The steps below are grounded in the supported code paths (`IChecklistService`, `ChecklistServlet`) and the configuration property patterns documented for other object types. Confirm the exact UI steps for exposing a checklist on a test run form/page in your Polarion instance before rolling this out broadly.
## Steps
### 1. Identify the checklist field on your test run type
A checklist on a test run is parsed and stored via a field, the same way as on work items, documents, and plans. `IChecklistService` exposes dedicated overloads for `ITestRun` — `parse(ITestRun testRun, String field)` and the corresponding `store` and `reset` calls — so the underlying save/read mechanism for test runs is a first-class, supported path, not a workaround.
Confirm (or create) the custom field that will hold the checklist data for your test run configuration.
### 2. Render the checklist on the test run
Test run checklists are rendered via `$checklistService.getChecklistView().testRun($testRun).checklist("testDone").render()` in a Velocity script block (see the screenshot below) — the same `getChecklistView` rendering entry point documented in [IChecklistService and Velocity Rendering API](/checklist/reference/api-service), fluently scoped to the target test run. The resulting configuration includes the `allMandatory` flag and a template URL that points at the **template test run** (in the `/testrun?id=...` format), which implies:
* Test runs support the same `allMandatory` semantics as work items and documents (when enabled, all items — not only mandatory ones — must be checked for the checklist to be considered complete).
* A test run can have its own dedicated **template test run**, referenced by a `/testrun?id=...` URL, distinct from how work item and document templates are resolved.
**getChecklistConf has a dedicated ITestRun overload**
[IChecklistService and Velocity Rendering API](/checklist/reference/api-service) confirms `getChecklistConf` has a dedicated `ITestRun` overload (`getChecklistConf(ITestRun testRun, String field)`), computing `readonly`/`adminPermission` from the test run's own permission check (`testRun.can().modify()`) rather than the work item path's license-authorization check. This is a first-class, supported path, not a workaround.
### 3. \[Optional] Point the test run at a template test run
Checklist templates for test runs are resolved from **the test run's own template test run** (`ITestRun.getTemplate()`), which is a different resolution path than the `workItemTemplateId` / `documentTemplateId` configuration properties used for work items and documents. Set up your template test run in Polarion's test run template configuration, and confirm it is configured as the template for the test runs you want to gate.
**Only POST is supported**
The checklist save endpoint only supports `doPost`. `doGet` and `doPut` requests to the same servlet always throw a `RuntimeException`. If you're probing the endpoint directly while diagnosing an integration issue, use POST — a GET or PUT will error even if your parameters are otherwise correct.
### 4. Configure gate enforcement (optional)
If the checklist should block a test run's workflow transition until items are checked, attach one of the workflow functions or conditions to your test run workflow. All three of the following explicitly support test runs as a target type, alongside work items and documents:
* **`ChecklistFailIfMandatoryUnchecked`** — a workflow function/action that aborts the transition with an error if mandatory items aren't checked.
* **`ChecklistMandatoryChecked`** — a workflow condition that gates whether the transition is even available, without throwing.
* **`ChecklistApplyTemplate`** / **`ChecklistResetToTemplate`** — workflow actions that (re)apply or reset the checklist to its template state on a transition.
Example workflow snippet applying the fail-if-unchecked function on a transition:
```xml theme={null}
dod
```
The `checklist` argument is required and accepts a comma-separated list of checklist field IDs — you can validate several checklists in one function call:
```xml theme={null}
dod,dor
```
**Missing checklist argument fails loudly**
If the `checklist` argument is omitted, the workflow function throws a `RuntimeException` with the message `checklist attribute missing for wf function: ChecklistFailIfMandatoryUnchecked` (or the equivalent message naming `ChecklistMandatoryChecked` for the condition). Double-check the argument name and spelling when wiring this into your workflow XML.
### 5. Reset behavior on transitions
`ChecklistResetToTemplate` resets the checklist back to its **template** state (discarding any checked/unchecked progress), which is different from `ChecklistUncheckAll`, which only clears checkmarks while keeping the existing item list. Both support test runs as a target type. `ChecklistResetToTemplate` also accepts an optional `skipForUsers` argument — a comma-separated list of user IDs for which the reset is skipped (useful for service/automation accounts that shouldn't have their checklist wiped on transition).
```xml theme={null}
dod
automation-bot
```
**Use apply-template on init, not on every transition**
For work item templates, Nextedy support's documented workaround for a Polarion template-copy bug is to add `ChecklistResetToTemplate` to the workflow's **init** action so the checklist field type is fixed right after item creation. The same idea applies conceptually to test runs that are created from a template test run — verify whether your test run creation flow needs an equivalent reset step if you see duplicated or malformed checklist entries after creation.
## Common pitfalls
**Save failures surface as a generic HTTP 500**
If a checklist fails to save on a test run, the servlet returns a generic HTTP 500 and logs a full parameter dump (project, testrun, checklist ID, data) to the server log for diagnostics. There's no user-facing detail beyond the 500 — check server logs first when troubleshooting failed saves.
**No dedicated setup guide for test run + LivePages was found in existing tickets**
Support has previously fielded requests to integrate Checklist into Polarion Test Run / Test Run Template Live Report Pages, and considered the integration too complex to explain in writing — opting for a live call instead. Treat this as a signal that test run + Live Report Page embedding may need hands-on verification in your environment rather than a pure copy-paste of a work item or document snippet.
## You should now see
After wiring the checklist field to your test run type and (optionally) attaching workflow functions, you should now see the checklist form extension rendered on the test run, with items checked/unchecked and saved back via POST. If you attached `ChecklistFailIfMandatoryUnchecked` or `ChecklistMandatoryChecked` to a transition, that transition should be blocked (or disabled) until all mandatory items carry a checked result state.
## See also
* [Set Up a Work Item Checklist](/checklist/guides/setup/work-items)
* [Set Up a Document (LiveDoc) Checklist](/checklist/guides/setup/documents)
* [Set Up a Plan Checklist](/checklist/guides/setup/plans)
* [Create a Checklist Template](/checklist/guides/templates/create-a-template)
* [Configure Gate Enforcement (DoD / DoR) and Freeze on Status](/checklist/guides/workflow-gates-and-freeze)
* [Save Errors and Version Compatibility](/checklist/guides/troubleshooting/save-errors-and-compatibility)
**KB Articles**
* Setup new document (LiveDoc) checklist
* How to create checklist template?
* Setup new Work Items checklist
**Support Tickets**
* [#332](https://support.nextedy.com/helpdesk/tickets/332)
* [#418](https://support.nextedy.com/helpdesk/tickets/418)
* [#235](https://support.nextedy.com/helpdesk/tickets/235)
**Source Code**
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/ChecklistServlet.java`
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/ChecklistAdminService.java`
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/IChecklistService.java`
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/wf/ChecklistFailIfMandatoryUnchecked.java`
* `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/wf/ChecklistApplyTemplate.java`