Set Up a Test Run Checklist - Nextedy Documentation

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.

Polarion Test Run list with a test run selected, showing the User Acceptance Test Done Checklist rendered below it with a Save button and 3 of 5 items completed

Verify in applicationThe 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.

Test Run Custom Fields administration page with a new testDone custom field being configured, with the field type dropdown open showing Text (multi-line plain text) selected

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, 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 overloadIChecklistService and Velocity Rendering API 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.

Test run gear menu with Customize Test Run Page highlighted, used to open the Test Run Report page editor

Confirmation dialog shown when editing a test run's report, offering to either Customize Shared Report (applies to every test run using the template) or Overwrite Shared Report (applies only to this test run)

Script Block widget in the Test Run Report page editor showing the Velocity script that calls checklistService.getChecklistView().testRun($testRun).checklist("testDone").render(), with the resulting empty checklist widget rendered below it

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.

Test run properties page showing the Template field set to Release Test, used to link the test run to its template test run

User Acceptance Test Done Checklist rendered on a test run created from a template, showing all 5 checklist items unchecked with 0 of 5 completion inherited from the template

Test run checklist save flow: browser POSTs to ChecklistServlet.doPost, which resolves the target by precedence (document, testrun, plan, workitem), resolves the ITestRun via a constructed ObjectId, stores the checklist data in a transaction, and returns HTTP 200 on success or HTTP 500 with a logged error on failure

Only POST is supportedThe 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:

<action>
    <function id="ChecklistFailIfMandatoryUnchecked">
        <arg name="checklist">dod</arg>
    </function>
</action>

The checklist argument is required and accepts a comma-separated list of checklist field IDs — you can validate several checklists in one function call:

<arg name="checklist">dod,dor</arg>

Missing checklist argument fails loudlyIf 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).

<action>
    <function id="ChecklistResetToTemplate">
        <arg name="checklist">dod</arg>
        <arg name="skipForUsers">automation-bot</arg>
    </function>
</action>

Use apply-template on init, not on every transitionFor 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 500If 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 ticketsSupport 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.

​Before you start

​Steps

​1. Identify the checklist field on your test run type

​2. Render the checklist on the test run

​3. [Optional] Point the test run at a template test run

​4. Configure gate enforcement (optional)

​5. Reset behavior on transitions

​Common pitfalls

​You should now see

​See also

Before you start

Steps

1. Identify the checklist field on your test run type

2. Render the checklist on the test run

3. [Optional] Point the test run at a template test run

4. Configure gate enforcement (optional)

5. Reset behavior on transitions

Common pitfalls

You should now see

See also