> ## 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.

# Test Run Checklist

> By the end of this tutorial, you will have a working checklist attached to a Polarion test run.

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 working checklist attached to a Polarion test run. You will create a custom field for test runs, embed the checklist widget into the test run report page, optionally configure a template from a test run template, and verify the setup by interacting with checklist items on a live test run.

## Prerequisites

* Nextedy CHECKLIST plugin installed and active (see [Installation](/checklist/getting-started/installation))
* A Polarion project with administrator access
* Permission to create custom fields and edit test run report pages
* At least one test run or test run template in your project

## Setup overview

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/Jklvz9qm2AdmIvBG/checklist/diagrams/getting-started/test-run-checklist/diagram-1.svg?fit=max&auto=format&n=Jklvz9qm2AdmIvBG&q=85&s=407e6c9f214b93b634e50abc8f5c6658" alt="diagram" style={{ maxWidth: "720px", width: "100%" }} width="720" height="180" data-path="checklist/diagrams/getting-started/test-run-checklist/diagram-1.svg" />
</Frame>

<Steps>
  <Step title="Create a checklist custom field for test runs">
    Create a new custom field on the Test Run object to store checklist data.

    1. Open your Polarion project and navigate to **Administration > Custom Fields > Test Run Custom Fields**
    2. Click **Add** to create a new field
    3. Set the following values:

    | Field Property | Value                            |
    | -------------- | -------------------------------- |
    | ID             | `testExecChecklist`              |
    | Name           | `Test Execution Checklist`       |
    | Type           | **Text (multi-line plain text)** |

    4. Save the custom field

    <Warning title="Field type is critical">
      The custom field **must** be of type **Text (multi-line plain text)**. Other field types are not compatible with the Checklist plugin and will produce an error when rendering.
    </Warning>

    You should see the `testExecChecklist` field listed in the Test Run Custom Fields table.

    <Tip title="Multiple checklists per test run">
      You can create several checklist fields on a single test run. For example, create `testSetup` for pre-execution checks and `testExecChecklist` for post-execution verification.
    </Tip>
  </Step>

  <Step title="Embed the checklist widget in the test run report page">
    Test run checklists are displayed using a script block widget on the test run report page, similar to document checklists.

    1. Open a test run in your project
    2. Click **Customize Report Page** in the test run toolbar
    3. Select **Customize Shared Report** to share the configuration across all test runs that use the same template

    <Tip title="Shared report template">
      Use **Customize Shared Report** when possible. This shares the layout between a test run and its test run template, so you only configure the checklist widget once. If you customize individual test runs instead, you must repeat this step for each test run.
    </Tip>

    4. In the report page editor, place a **Script Block Widget** where you want the checklist to appear
    5. Enter the following rendering call in the script block:

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

    <Note title="Field ID reference">
      The `"testExecChecklist"` string in the `checklist()` call must match the ID of the custom field you created in Step 1. Substitute your actual field ID if it differs.
    </Note>

    6. Save the report page

    You should now see the checklist widget on the test run report page. It displays an empty checklist until you define template items.
  </Step>

  <Step title="Configure a checklist template via test run template">
    Set up a template so that test runs created from a test run template automatically inherit predefined checklist items.

    1. Open your test run template in Polarion (navigate to **Testing > Test Run Templates** and select the relevant template)

    2. If the checklist widget is not yet visible on the test run template, repeat Step 2 for the template's report page

    3. Add checklist items directly to the test run template's checklist widget -- for example:

       * Verify test environment configuration
       * Confirm test data loaded
       * Execute all test cases
       * Review test results
       * Archive test artifacts

    4. Save the test run template

    Test runs created from this template will inherit the checklist items you defined. The template merge happens automatically when a test run is created.

    <Info title="Verify in application">
      Template merging for test runs follows the same pattern as work item templates. The Checklist plugin merges items from the template into each new test run's checklist. Verify that items appear correctly on a newly created test run.
    </Info>
  </Step>

  <Step title="Verify the checklist on a test run">
    1. Create a new test run from the template you configured in Step 3
    2. Open the test run and scroll to the checklist section on the report page

    You should see the template checklist items displayed with their initial result state (Empty).

    3. Walk through each checklist item and set its result state as you progress through the test execution:

    | Result State | Typical Use in Test Runs             |
    | ------------ | ------------------------------------ |
    | OK           | Step completed successfully          |
    | NOK          | Step failed -- issue identified      |
    | N/A          | Step not applicable to this test run |
    | Pending      | Step deferred to a follow-up run     |
    | Empty        | Step not yet addressed               |

    4. Save the test run to persist the checklist state

    <Tip title="Workflow enforcement">
      You can add workflow conditions to prevent closing a test run until all checklist items are addressed. See [Workflow Gates and Validation](/checklist/guides/workflow-gates) for details on configuring the `ChecklistAllChecked` or `ChecklistMandatoryChecked` conditions for test runs.
    </Tip>
  </Step>
</Steps>

## Next steps

Your test run checklist is now operational. Continue with these topics:

* [Work Items Checklist](/checklist/getting-started/work-items-checklist) -- set up checklists on work items
* [Document Checklist](/checklist/getting-started/document-checklist) -- add checklists to LiveDocs
* [Plan Checklist](/checklist/getting-started/plan-checklist) -- add checklists to project plans
* [Workflow Gates and Validation](/checklist/guides/workflow-gates) -- enforce checklist completion before test run status transitions
* [Creating and Managing Templates](/checklist/guides/templates) -- advanced template management
* [Configuration Properties](/checklist/reference/configuration-properties) -- full reference of all `nextedy.checklist.*` properties

<LastReviewed date="2026-07-02" />