Test Management

Overview

The Tests tab in your project is where you manage your entire test suite. It uses a split-panel layout: a tree view on the left for browsing and organizing tests, and a detail panel on the right that shows the full content of the selected test.

Tests can be created in two ways: automatically by the AI through "Generate test cases" tasks, or manually through the "Create Test" dialog. Both methods produce tests that go through the same review and versioning workflow.

Test types

qtrl supports two test types depending on how you want to structure your testing:

Test case (Structured steps)

These are traditional test cases with clearly defined steps. Each step has a description of what to do and an expected result. When the AI executes a structured test, it follows the steps in order and checks the expected outcomes.

Structured tests are ideal when you need precise, repeatable verification of specific functionality. They provide clear pass/fail criteria and are easy to review.

Freeform instructions

Instead of step-by-step instructions, freeform tests contain a block of natural language text describing what should be tested. The AI interprets the instructions and decides how to execute them.

Freeform tests work well for complex workflows that are hard to break into discrete steps, or when you want the AI to use its judgment about how to validate something.

Test properties

Each test has several properties that help you organize and track your test suite:

• Name: a descriptive title for the test.
• Display ID: an auto-generated identifier (like TC-1, TC-2) that makes tests easy to reference.
• Priority: indicates the importance of the test. Options are critical, high, medium, and low.
• Status: reflects where the test is in its lifecycle (see below).
• Preconditions: any setup or state that needs to exist before the test can be executed.
• Requirement IDs: tags that link the test to external requirements (for example, REQ-123) for traceability.

Organizing tests with folders

The tree view on the left side of the Tests tab lets you organize tests into a folder hierarchy. You can create folders, nest them inside other folders, and drag tests between folders to keep your suite structured.

Right-clicking in the tree view opens a context menu where you can create new folders or select multiple tests. There is also a search box at the top that filters the tree to quickly find specific tests by name.

A well-organized folder structure makes it easier to find tests, select groups for test runs, and understand your overall test coverage. See Best Practices: Test Management for tips on organizing effectively.

Versioning

Tests in qtrl go through a versioning workflow that helps you maintain quality while allowing the AI to evolve tests based on what it learns during execution.

When a test is first created (whether by the AI or manually), it starts at version 1 with a draft status. A full snapshot of the test content is stored as the initial version.

Every time a test's content changes (name, steps, type, priority, preconditions, or freeform instructions), the version number increments and a new snapshot is stored. This happens atomically: the test update, step changes, version snapshot, and audit entry are all created in a single database transaction, so you never end up with partial or inconsistent data.

After the test is executed, the AI may discover that some steps need adjustments based on how the application actually behaves. These deviations are recorded, and a new version is created that incorporates the changes. The updated version moves to a "pending review" status.

You then review the changes and either approve or reject the new version. Approved tests become part of your active test suite and can be included in test runs. Rejected tests go back to the drawing board for further refinement.

The History section of each test shows all versions along with what changed and when. You can restore any previous version, which creates a new version with the content from the target version while preserving the full history.

Audit trail

Every change to a test, test run, test execution, or test folder is recorded in an immutable audit log. The audit log captures who made the change, what changed (old and new values), when it happened, and the type of action (created, updated, deleted, restored, or status changed).

The audit log is append-only: entries cannot be modified or deleted, even by administrators. Each entry is linked to the previous entry via a SHA-256 hash chain, providing tamper-evident integrity verification.

Audit entries survive entity deletion. If a test or test run is deleted, its audit history remains intact for compliance and forensic purposes.

You can view the audit trail for any test in the test details panel under the History section, and for any test run in the test run details view.

Test status lifecycle

A test moves through the following statuses during its lifetime:

• Draft: the test has been created but not yet reviewed or executed. This is the starting point for all new tests.
• Pending review: the test has been updated (usually after execution) and needs someone to review the changes.
• Approved: the test has been reviewed and accepted. It is ready to be included in test runs.
• Rejected: the test was reviewed and the changes were not accepted. It needs to be revised.

Bulk actions

You can select multiple tests using the checkboxes in the tree view. Once selected, a bulk actions bar appears at the bottom with options to run the selected tests as a group or delete them. This is a quick way to create test runs from a specific set of tests.