TestRail for Test Case Management: Setup to Execution

TestRail for Test Case Management: Setup to Execution

Test case management sounds like overhead until you're six months into a product with 300 test cases, three QA engineers, a sprint starting Monday, and no clear picture of what's been tested, what's failing, and which features are actually ready to ship. TestRail is the tool that prevents that situation.

This guide covers TestRail from initial setup through a complete test execution workflow: creating projects, building test suites, writing effective test cases, and running tests against milestones. By the end, you'll have a structure that scales from a solo QA engineer to a team of ten.

Understanding TestRail's Structure

TestRail organizes work in a hierarchy you need to understand before setting anything up:

Project
├── Test Suite(s)
│   ├── Section (folder)
│   │   ├── Test Case
│   │   ├── Test Case
│   │   └── Test Case
│   └── Section
│       └── Test Case
├── Milestone (release or sprint)
│   └── Test Plan
│       ├── Test Run (Suite A + filters)
│       └── Test Run (Suite B + filters)
└── Test Run (ad-hoc, not in a plan)

Projects map to products or major components. A startup typically has one project. An enterprise might have separate projects for web app, mobile app, and API.

Test Suites are collections of test cases. In "multiple suites" mode, you can have one suite per feature, one per release, or one master suite. For most teams, a single master suite with sections is simplest.

Sections are folders within a suite. Organize by feature, user flow, or application area.

Milestones represent releases, sprints, or major QA cycles. They give you a way to track testing progress against a specific deliverable.

Test Plans group multiple test runs under a milestone. Use them when you're testing the same features across different configurations (browsers, OS, mobile devices).

Test Runs are an execution instance of test cases. A test run takes a set of cases, assigns them to testers, and tracks pass/fail results.

Project Configuration

When creating a project, choose between two test suite modes:

Single repository — one master suite for the project. Best for most teams. All test cases live in one place, organized by sections.

Multiple suites — separate suites per feature or module. Better when you have large teams with clear ownership boundaries and different teams manage different suites.

For most SaaS products and teams under 20 engineers, single repository with organized sections is the right choice. The overhead of multiple suites — managing which suites apply to each run — isn't worth it until you have a genuinely large test library (1000+ cases) with strict ownership boundaries.

Building Your Test Suite Structure

Sections should mirror how users experience your product, not how it's implemented internally. A section called "Authentication" is better than "AuthController" because it maps to user flows and makes sense to non-engineers reviewing results.

Good section structure for a SaaS product:

Authentication
├── Login
├── Registration
├── Password Reset
└── SSO / OAuth

User Management
├── User Profile
├── Team Members
├── Roles & Permissions
└── User Invitations

Core Feature: [Name]
├── Happy Path Flows
├── Edge Cases
└── Error States

Integrations
├── API Authentication
├── Webhooks
└── Third-Party Integrations

Billing
├── Subscription Management
├── Payment Methods
└── Invoice History

Create sections before writing any test cases. The structure is much harder to change once cases exist.

Writing Effective Test Cases

Poor test cases are the biggest source of confusion in TestRail. "Test login functionality" tells a tester nothing. Here's what a good test case contains:

Title: Clear action + expected outcome. "Login with valid credentials — user redirected to dashboard" not "Login test".

Preconditions: What state must exist before the tester starts. Be specific: "User account exists with email test@example.com and password TestPass123!" not "User is registered".

Steps: Numbered, atomic actions. Each step should be executable by someone who's never seen the product before.

Expected Result: Observable outcome. "Dashboard page loads, showing the user's name in the top-right navigation" not "login works".

Here's a complete example:

Title: Login with valid credentials redirects to dashboard

Preconditions:
- Active user account exists: email=qa@example.com, password=QATest123!
- User is on the login page (https://app.example.com/login)
- No active session exists (clear cookies if needed)

Steps:
1. Enter "qa@example.com" in the Email field
2. Enter "QATest123!" in the Password field
3. Click the "Sign In" button

Expected Result:
- User is redirected to https://app.example.com/dashboard
- Dashboard page loads completely (no loading spinner visible)
- User's name "QA Tester" appears in the top-right navigation
- No error messages are displayed

Compare this to: "Enter credentials and click login. Verify dashboard loads." One of these is a test. The other is a note.

Test Case Types

TestRail supports multiple case types:

Functional — the default. Testing a specific feature or flow.

Automated — test cases that have corresponding automation. Link these to your CI results (covered in the API post).

Smoke — quick sanity checks. Tag high-priority cases so you can create smoke test runs quickly.

Regression — full coverage runs before releases.

Use the Type field consistently. When you need to spin up a quick smoke test for a hotfix, filtering to "Smoke" cases should give you the right 20 cases immediately.

Priority Levels

Assign priority thoughtfully:

  • Critical: Core functionality that, if broken, blocks most users (login, payment, core feature)
  • High: Important features that affect many users
  • Medium: Standard features, non-critical paths
  • Low: Edge cases, rarely-used features, cosmetic issues

The purpose of priorities is filtering — before a release, you need to know "are all Critical cases passing?" not "are all 400 cases passing?"

Test Runs vs. Test Plans

Ad-hoc test runs are quick. Create a run, select cases, assign testers, execute. Use them for:

  • Hotfix verification (run just the affected area)
  • Exploratory testing sessions
  • Quick smoke tests after deployment

Test plans under milestones are structured. Use them for:

  • Sprint-end testing
  • Release candidate validation
  • Regression cycles

Creating a test plan for a release milestone:

  1. Create milestone: "v2.4 Release — June 15, 2026"
  2. Create test plan within the milestone: "v2.4 Regression"
  3. Add test runs to the plan:
    • "Chrome Desktop" — all functional cases, assigned to Tester A
    • "Safari Mobile" — smoke cases + new features, assigned to Tester B
    • "API Regression" — all API test cases, runs automatically via CI

The test plan gives you a single dashboard view of release readiness across all environments and configurations.

Assigning Tests and Tracking Progress

When creating a test run, you can assign individual cases to specific testers or assign the entire run to one person. For a team of multiple QA engineers:

  • Assign by section: Tester A owns Authentication, Tester B owns Billing
  • Assign by priority: Tester A takes all Critical/High, Tester B takes Medium/Low
  • Assign by estimated time: balance the load based on case complexity

The test run dashboard shows real-time progress: how many cases are Untested, In Progress, Passed, Failed, or Blocked. Blocked cases are particularly important — they indicate a dependency that prevents execution (environment not ready, prerequisite bug not fixed).

Recording Test Results

Results in TestRail go beyond pass/fail:

  • Passed: Case executed as written, all expected results observed
  • Failed: Case executed, expected result not observed. Add a defect reference.
  • Blocked: Case cannot be executed. Document why.
  • Retest: Previously failed, fix deployed, needs re-verification.

When marking a case failed, always include:

  • Actual result (what actually happened)
  • Defect ID (Jira ticket, GitHub issue)
  • Screenshot or recording (use the attachment field)

This information turns TestRail from a checkbox tool into a debugging aid. A developer looking at a failed test should be able to reproduce the issue from the TestRail entry without needing to track down the tester.

Milestones for Sprint Tracking

For agile teams, create a milestone per sprint:

  • "Sprint 42 — May 26 to June 9, 2026"
  • Set milestone due date to the sprint end date
  • Create test runs for new features added in the sprint
  • Track completion percentage in the milestone dashboard

TestRail's milestone view shows you completion percentage, pass rate, and time remaining. When a sprint ends at 67% completion with 15% failures, you have a concrete, defensible answer to "is this ready to ship?"

Closing the Loop: Defects and Retest Cycles

When a case fails and a developer fixes the defect, the workflow in TestRail is:

  1. QA marks case as Failed, links defect ID
  2. Developer fixes the defect, updates the issue to "Ready for QA"
  3. QA opens the test run, filters to "Failed" cases related to the defect
  4. QA re-executes the case, marks as Passed or Retest

The Retest status is specifically designed for this cycle — it signals "was previously failing, needs verification of a fix" distinct from "untested".

Reporting

TestRail's built-in reports give you:

Activity report: What was tested in a date range, by whom. Useful for sprint retrospectives.

Summary report: Overall pass/fail/blocked counts for a test run or plan. Use this in release go/no-go decisions.

Milestone report: Progress across all test plans in a milestone. The executive view of release readiness.

Comparison report: Compare two test runs (this sprint vs. last sprint, staging vs. production). Shows which previously passing cases are now failing.

Export any report to CSV for further analysis or stakeholder distribution.

The test case management infrastructure you build in TestRail is an asset that compounds over time. Suites you write for v1.0 catch regressions in v2.0. Milestones you document become a historical record of release quality. The time invested up front pays back every time you ship with confidence.

Read more

Start now free