Aqua ALM Test Management: Getting Started

Aqua ALM is an enterprise test management platform built around one idea that most tools ignore: requirements and tests belong together. Where tools like TestRail or Zephyr treat test cases as standalone records, Aqua ALM ties every test case back to a requirement, giving you traceability from business need to test execution result. This post walks through setting up a project, building your test case hierarchy, running tests, and reading the reports that come out the other side.

What Aqua ALM Actually Is

Aqua ALM (developed by aqua cloud, formerly known as aqua) covers the full application lifecycle from requirements capture through defect tracking. The test management module sits at the center, connected to requirements on one side and defects on the other.

The platform runs as a web application and is available both as a cloud-hosted SaaS and as an on-premise installation. Large enterprises in regulated industries (banking, pharma, defense) often choose the on-premise option because of data residency requirements. The cloud version removes infrastructure overhead and suits teams that want to get started quickly.

Key concepts:

• Projects -- top-level containers, usually one per product or program
• Folders -- hierarchical containers within a project for organizing test cases
• Test cases -- individual test procedures with steps, expected results, and metadata
• Test runs -- instances of executing test cases, capturing actual results
• Requirements -- imported or created specs that link to test cases for traceability

Setting Up a Project

After logging in, navigate to the Projects section and click New Project. You will provide a project name, key (short identifier used in issue references), and optionally a description.

Once the project exists, configure its settings:

1. Fields -- Aqua supports custom fields on test cases, requirements, and defects. Define the fields your team actually uses before importing anything. Common additions include Priority, Component, Test Type, and Automation Status.
2. Users and roles -- Assign team members as Testers, Test Managers, or Admins. Roles control what each person can create or modify.
3. Workflows -- Test cases and defects follow configurable status workflows. The default workflow (Draft > Review > Approved) works for most teams but can be adjusted.

Building Your Test Case Hierarchy

Aqua uses a folder tree to organize test cases. A practical starting structure for a web application:

My Project
├── Functional Tests
│   ├── Authentication
│   ├── User Management
│   └── Checkout Flow
├── API Tests
│   ├── Orders API
│   └── Inventory API
└── Regression Suite
    └── Smoke Tests

Folders are reusable across test runs, so invest time in getting the structure right early. Renaming folders after you have linked requirements to them can disrupt traceability links.

Creating a Test Case

Inside a folder, click New Test Case. Fill in:

• Title -- descriptive, action-oriented ("Verify checkout with expired credit card")
• Preconditions -- state the system must be in before the test starts
• Steps -- each step has an action and an expected result
• Post-conditions -- cleanup or state after the test completes

For example:

Aqua lets you nest steps into groups, which helps for longer test cases with setup, execution, and teardown phases.

Creating and Running Test Runs

A test run is an execution instance of a set of test cases. Create one from the Test Runs section:

1. Click New Test Run
2. Select the project and optionally a version or build label
3. Choose which test cases to include -- you can pick folders, individual test cases, or filter by field values
4. Assign testers to specific test cases if the run is distributed across a team

During execution, testers open their assigned test cases, step through each action, and mark each step Passed, Failed, or Blocked. Failed steps prompt for a defect -- Aqua can create the defect directly in its own defect tracker or push it to an external system like Jira.

Test runs capture the execution environment (browser, OS, test data version), timestamps for each step, and any attachments (screenshots, log files).

Reading the Reports

Aqua generates several reports from test run data:

Test Execution Report -- Shows pass/fail/blocked counts for a run. Useful for daily status during a test cycle.

Requirements Coverage Report -- Maps requirements to linked test cases and their execution status. This is where Aqua's traceability pays off -- you can see at a glance which requirements have no tests and which have untested or failing tests.

Defect Density Report -- Counts defects by component or folder, helping identify which areas of the application are most problematic.

Test Case Effectiveness -- Tracks which test cases have historically found defects, helping prioritize which tests to always include in regression runs.

Reports can be exported to PDF or Excel. Scheduled report delivery via email is available in the enterprise tier.

Getting the Most from the Hierarchy

A common mistake is creating flat folder structures with hundreds of test cases in a single folder. Aqua's reporting and filter system works better with a deeper hierarchy because you can slice run results by folder.

Tag test cases with custom field values (like Test Type = Smoke) rather than creating separate folders for cross-cutting concerns. Then use those field values as filters when building test runs, rather than manually selecting individual test cases.

Start by importing any existing test cases from Excel or CSV using Aqua's import tool. Map columns to Aqua fields during import, and assign each test case to a folder as part of the import configuration.

Once your test case library is in place, the next step is linking those test cases to requirements -- which is where Aqua's traceability model becomes the main reason to use it over simpler tools.