Important

This is use case description is a draft. It will be detailed and improved based on feedback from the community. If you have any feedback please contact us.

Test management in OpenProject

Purpose

This guide describes how OpenProject can be used for lightweight test management by modeling test plans, test cases, and test runs using built-in features such as work package types, workflows, custom fields and project templates. It enables teams to manage and execute tests within the same environment they already use for project and requirements tracking.

Scope and assumptions

This use case is intended for teams that:

  • Already use OpenProject for project planning and requirements management
  • Want to include manual or semi-automated testing workflows
  • Need traceability between requirements, test cases, executions, and defects

This setup is not a replacement for full-scale test automation or advanced lab management tools, but rather a structured and integrated approach to test tracking.

Note

At OpenProject, automated testing is a key part of our development process. It helps us detect bugs early and avoid regressions, especially as the codebase grows. We use continuous integration and deployment (CI/CD) to ensure that changes are tested and released quickly and reliably. You can see our automated test runs on GitHub Actions. In addition to automated tests, we also perform smoke tests and exploratory testing to cover areas that are harder to automate and to validate the overall user experience.

Structure and terminology

Test management entities

Core entities

Concept OpenProject entity
Requirements Work package (e.g., type Feature or User Story)
Test case Work package type Test Case
Test run Work package type Test Run (child of test case)
Test plan Project (created from a template)
Version under test OpenProject Version field on test runs
Defect Work package (e.g., type Bug)

Relationships

  • Each Feature or User Story may relate to one or more test cases.
  • Each Test Case defines a reusable test specification.
  • Each Test Case has one or more Test Runs (child work packages).
  • A Test Run is specific to one software version.
  • Test Plans are realized as individual projects per version, created from a reusable template.
  • Bugs can be linked to failed Test Runs.

This structure supports traceability from requirements to execution and defect reporting.

1. Test preparation and execution

1.1 Creating a test plan (project)

A new test plan project is created based on a predefined template using the create project form.

create test plan

1.2 Adjusting the created test plan

In the next step the newly created test plan is adjusted by specifying the test object. The easiest way is to select all work package (CMD + A) -> right click -> bulk edit.

  • Version of the test object (version ideally shared from the development project)
  • Tester
  • Environment

For all test runs which are not planned the status should be adjusted to something like Not planned.

adjust test plan

1.3 Test execution

  1. Testers open the project corresponding to the release version.
  2. Each test run is executed individually:
    • Preconditions are verified
    • Steps are performed
    • Results are recorded
    • Status is updated (e.g., Passed, Test failed, Blocked)
  3. If failures occur, related defects (bugs) are created and linked.
  4. Boards, filters, or hierarchy views are used to monitor test progress and coverage.
  5. The test result can be document creating a pdf report of the test status and results.

create test report

2. Configuration guidance

This section provides guidance on how to configure OpenProject for test management. It assumes familiarity with OpenProject administration features.

2.1 Configuration example: Test Cases (work package type)

The work package type Test case can be configured so it shows the relevant information:

  • Test runs (related work packages table children)
  • Tested features (related work packages requires)
  • Priority
  • Tested module (custom field of type Hierarchy)

Here you find an example for a test case.

test case configuration example

2.2 Configuration example: Test Run (work package type)

The work package type Test run can be configured so it shows the relevant information:

  • Test specification inlcuding preconditions, excecution steps and testresults: Description field Tested features (related work packages requires)
  • Priority
  • Tester (custom field of type user)
  • Identified bugs (related work packages related to)

Here you find an example for a test run.

test run configuration example

2.5 Workflow and statuses

  • Define custom statuses such as:
    • New,
    • In progress
    • Test passed
    • Test failed
    • …
  • Create a simple workflow for test runs with allowed transitions
  • Optionally restrict who can move a test run to Test passed.

test run workflow example

2.3 Roles and permissions

  • Define useful roles such as:

    • Tester
    • Test Manager

  • Add permissions such as:

    • Edit work packages

2.4 Custom fields

Define custom fields that describe the test object such as:

  • Test environment (type hierarchy)
  • Tester (custom field type user)