> ## 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 (Tutorial)

> Nextedy CHECKLIST can enforce a structured checklist on Polarion test runs, not just 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 <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## What you will achieve

By the end of this tutorial you will have:

* A custom field on the test run object that stores checklist data
* The checklist rendered and editable on the test run's report page
* A test run template that pushes the checklist automatically to every test run created from it

On the test run's report page, a Script Block Widget calls `$checklistService.getChecklistView().testRun($testRun).checklist("testDone").render()`, which renders the `testDone` checklist inline.

<Tip>
  **Work items work the same way**

  If you are looking to add a checklist to a work item instead, see [Your First Checklist](/checklist/getting-started/your-first-checklist). If you need a checklist on a plan, see [Set Up a Plan Checklist (Tutorial)](/checklist/getting-started/setup-plan-checklist).
</Tip>

## Prerequisites

* Administrator access to the Polarion project (**Project Administration**)
* Checklist installed and licensed on your Polarion instance
* At least one existing test run or test run template to work with

<Steps>
  <Step title="Create a custom field to hold the checklist">
    The checklist itself is stored as plain text in a custom field on the test run object.

    1. Go to **Project Administration > Custom Fields**.
    2. Create a new custom field of type **Text (multi-line plain text)**.
    3. Give it a short, memorable ID — for example `testDone`.

    **What you should see:** the new field listed among your test run custom fields, with type `Text (multi-line plain text)`.

    <Note>
      **Multiple checklists are fine**

      You can create more than one checklist custom field on the test run object — for example one for `testDone` and another for a separate review gate. Each is configured and rendered independently.
    </Note>
  </Step>

  <Step title="Show the checklist on the Test Run Report page">
    Next, expose the checklist field on the report page that testers actually see.

    1. Open your test run, click the gear/actions menu, and choose **Customize Test Run Page**.
    2. Choose **Customize Shared Report** if it's available, so the same layout applies to both the test run and its template. Otherwise you will need to repeat this step for every individual test run.
    3. Drag a **Script Block Widget** onto the report page, wherever you want the checklist to appear.
    4. Enter the following line into the Script Block Widget:

    ```text theme={null}
    $checklistService.getChecklistView().testRun($testRun).checklist("testDone").render()
    ```

    Replace `testDone` with the ID of the custom field you created in Step 1.

    5. Save the report.

    **What you should see:** the checklist form extension rendered directly on the test run's report page, with its items ready to be checked off.

    <Warning>
      **Match the field ID exactly**

      The string passed to `.checklist(...)` must exactly match the custom field ID from Step 1. A mismatched ID is a common cause of a checklist that fails to render or appears empty.
    </Warning>
  </Step>

  <Step title="Define a checklist template">
    Rather than typing checklist items by hand on every test run, define them once on a test run template so every new test run starts pre-populated.

    1. Open your test run template by clicking the template link in its properties.
    2. If the checklist widget is not visible on the template's report page, repeat Step 2 for the template itself.
    3. Enter your checklist items directly into the checklist form extension on the template.

    **What you should see:** the checklist items you defined now also appear automatically on test runs created from this template — you no longer need to re-enter them for each run.

    When a new test run is created from the template, its `testDone` field is populated with a copy of the same checklist items defined on the template (for example Smoke tests pass, Regression pass, Sign-off recorded).

    <Info>
      **Verify in application**

      Whether template item edits made *after* a test run is already created automatically re-sync into that existing test run's checklist should be confirmed in your environment before relying on it for audit purposes.
    </Info>
  </Step>
</Steps>

## Next steps

* [Your First Checklist](/checklist/getting-started/your-first-checklist) — the equivalent walkthrough for work items
* [Set Up a Plan Checklist (Tutorial)](/checklist/getting-started/setup-plan-checklist) — apply the same pattern to Polarion plans
* [Concepts](/checklist/concepts/index) — understand result states, templates, and workflow gates before configuring gate enforcement on your test runs

<Accordion title="Sources">
  **KB Articles**

  * Setup New Plan Checklist
  * Setup New Test Run Checklist
  * Setup new Work Items checklist

  **Support Tickets**

  * [#235](https://support.nextedy.com/helpdesk/tickets/235)
  * [#418](https://support.nextedy.com/helpdesk/tickets/418)
  * [#325](https://support.nextedy.com/helpdesk/tickets/325)

  **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/ChecklistConf.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/ChecklistMandatoryChecked.java`
  * `proc-checklist-src/com.nextedy.polarion.checklist/src/com/nextedy/polarion/checklist/internal/ChecklistService.java`
</Accordion>

<LastReviewed date="2026-08-31" />