Skip to main content

​
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.
Work items work the same wayIf you are looking to add a checklist to a work item instead, see Your First Checklist. If you need a checklist on a plan, see Set Up a Plan Checklist (Tutorial).

​
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
1

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).
Multiple checklists are fineYou 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.
2

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:
Replace testDone with the ID of the custom field you created in Step 1.
  1. 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.
Match the field ID exactlyThe 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.
3

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).
Verify in applicationWhether 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.

​
Next steps

KB Articles
  • Setup New Plan Checklist
  • Setup New Test Run Checklist
  • Setup new Work Items checklist
Support TicketsSource 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
Last modified on August 31, 2026