Test Cases

User Guide

BriefSpec

1. Introduction

Test Cases in BriefSpec describe how your team will verify that software works as expected. Each Test case includes a Title, objective, prerequisites, test data, and step-by-step instructions with expected results. Test cases live inside a project and can be linked to requirements from your backlog or project phases.

This guide explains how to create, manage, and use project Test Cases – from authoring through test execution and defect reporting. It is written for Authors, Testers, and Project Managers. Test Case Library Insights (indexing for AI reuse) is covered in the Test Library Insights guide.

What you can do with Test Cases

  • View and search all test cases for a project in list or card (grid) view.
  • Create test cases with AI assistance.
  • Generate multiple test cases at once from linked requirements.
  • Edit, move through Draft / Reviewed / Published, clone, link, import, export, and regenerate test cases.
  • Assign Assignees on a test case so those users can later be used as Testers when the case is added to a Test Cycle.
  • Assign test cases to test cycles for execution by Testers.
  • Trace test cases back to requirements and forward to defects when tests fail.

 

2. Accessing Test Cases

Test cases are managed at project level.

  1. Sign in to BriefSpec and open Home.
  2. Select the project you are working on.
  3. In the project sidebar, open Testing > Test Cases. The module must be active on the project template, your role needs view-test-cases (or a related Test Cases privilege), and your plan needs module_test_cases.
  4.  

Everything on this tab applies only to the project you have open. If you do not have permission to view Test Cases, the item may be hidden. If the plan does not include Test Cases, the item can appear disabled with an upgrade tooltip.

  •  

3. The Test Cases Screen

List view and grid view

Use the toolbar to switch between List and Grid. Both views show the same data. Search placeholder: Search test cases… Status filter pills: All, Draft, Reviewed, Published. Also Advanced Filters, column preferences, Download, Import, bulk regenerate, bulk delete, and New Test Case.

List View

Grid View

Columns you will see (list view)

ColumnWhat it means
Test Case IDUnique identifier (for example, TC0000010).
TitleShort description of the Test case.
RequirementsRequirement or user story IDs linked to this test case.
PhaseProject phase the Test case is associated with.
Test CyclesTest cycles this case has been assigned to.
PillarThe high-level software area or product suite the Test Case belongs to
Epics / ModulesEpic or module (application area) for the test case. List header: EPICS/MODULES.
StatusDraft, Reviewed, or Published.
Created On / ByCreation metadata may appear in filters (Created By / Created Date). Default list also includes Tags, Info, and Actions.
AssigneeProject users assigned to this test case. When the case is added to a Test Cycle, these users can be inherited as Testers if they are on the Section Team.

Row actions menu

From the list, open the options menu (⋮) on a row for common actions:

  • Edit — open the test case editor.
  • Download — export when download is enabled for your role.
  • Clone — duplicate the test case.
  • Link requirement — connect the test case to a sprint/milestone and user story or requirement.
  • Delete – remove the test case (Draft or Reviewed only; Published cannot be deleted). Own vs All depends on your privilege condition.
  •  

Search and filters

  • Search test cases… – type keywords to search across the list.
  • Status pills – filter by All, Draft, Reviewed, or Published.
  • Advanced Filters – build rules on Test Case ID, Title, Software, Epic, Phase, Status, Test Case Type, Requirement ID, Tags, Created By, Created Date. List column Pillar maps to the software/pillar scope (filters may say Software).

Active filters appear as chips above the list. Your filter choices are remembered while you work in the same project. The same Advanced Filters are also available in the page header while you edit a test case in the split editor (see Viewing and Editing a Test Case).

Selecting multiple test cases

Use row checkboxes to select one or more test cases or select all on the current page. You can also select all test cases that match your current filters for bulk download. With one or more rows selected, use Assignee on the bulk bar to Replace, Add, or Remove assignees across the selection, then Apply.

4. Draft, Reviewed, and Published Status

Every test case has a status that controls what you can change: Draft, Reviewed, or Published (stored value Publish is shown as Published).

Typical flow: Draft while authoring, Reviewed when checked, Published when ready for cycles (Confirm Publish). Bulk regenerate and bulk delete apply to eligible selected rows (regenerate up to 20; delete skips Published).

StatusTypical use
DraftWork in progress. You can edit, delete, link/de-link, and assign.
ReviewedReviewed for readiness. Still editable and deletable. Link/de-link allowed. Not yet locked like Published.
PublishedReady for test cycles and execution. Editing and link/de-link are locked until Convert to Draft & Edit.
  • Draft and Reviewed are editable. Published is locked for edit and for link/de-link. To change a Published test case, use Convert to Draft & Edit when offered (then you can also move to Reviewed).
  • Test cases can be deleted in Draft or Reviewed status. Published test cases cannot be deleted from the list.
  • To change requirement links on a Published test case, convert to Draft or Reviewed first (message: Convert to Draft or Reviewed to modify requirements).

5. Creating a Single Test Case (AI-Assisted)

When AI is enabled for your organization and plan, you can create one test case at a time with New Test Case (requires add-test-cases). The slide-in is titled Create a Test Case.

  1. Open the project Testing > Test Cases tab.
  2. Click New Test Case. If AI is disabled for your tenant or plan, this option may be unavailable; contact your administrator.
  3. Select Pillar, Epic/Module, optional Phase, Test Case Type, and Requirement when required (mandatory_requirement_link on the Test Cases template module).
  4. For New Test Case (single AI create), Test Case Type can be Positive, Negative, Boundary, or Edge.
  5. Phase is optional. Enter the prompt (and optional project document references when offered), then continue.
  6. Click Generate Test Case. Review the generated Test Data and Test Steps. Use Stop Generating if you need to cancel.
  7. Save the test case. It is created in Draft status.

6. Generating Test Cases from Requirements

You can create many test cases at once from requirements already in your project – typically from Phase (Generate Test Cases privilege generate-test-cases).

  1. Select one or more requirements (User Stories or RTM items).
  2. Choose Generate Test Cases from the action menu. You can select up to 500 requirements. Selecting more than 20 runs generation in the background.
  3.  
  5.  
  6. In the Project Analysis & Test Options dialog, review counts (stories in package, Module/Epics in User Stories, Manual Effort per TC).
  7. Select which types to generate under Select Test Case Types: Positive Test Cases, Negative Test Cases, Boundary Test Cases, and/or Edge Test Cases. Add Special instruction when required.
  8.  
  10.  
  11. Upon selecting the Test Case Type, if multiple requirements have been selected, Test cases already generated for the combination of requirement and the Test Case type will be listed as an Exception and the rest will be processed for Test case generation.
  12. Click Generate Test Cases and wait for analysis and generation to complete.
  13. On the Results step, review generated results (Manual Effort Saved), optional Test Case Library used / Test Case Library not used badges when Library Insights examples were attached, then Save. You can Regenerate or Close.

7. Viewing and Editing a Test Case

Open a test case from the list or grid to see the detail editor with these tabs:

  • Overview – Test Case ID, Test Case Type, Status, Pillar, Epic / Module, Tags, Assignee, Title, Requirements, Test Cycles, Objective, Prerequisites (read-only).
  • Test Data — key/value pairs used during the test.
  • Test Steps — numbered steps with expected results.
  • Comments — team discussion.
  • Attachments — supporting files.
  • Audit Trail – history of changes (privilege activity-test-cases).

Required fields include Title (and Objective when the form requires it). Save your changes with the save control. Publishing confirms with Confirm Publish – once Published, the case cannot be edited until converted.

Advanced Filters while editing

When you open a test case from the list or grid, the editor opens in a split layout: a sidebar of test cases on the left and the detail tabs on the right. In the page header, use Advanced Filters (filter icon) to narrow which test cases appear in the sidebar without leaving the editor.

  • Click the Advanced Filters icon to open the same filter drawer as on the list. Build rules on Test Case ID, Title, Software, Epic, Phase, Status, Test Case Type, Requirement ID, Tags, Created By, and Created Date.
  • Active filters appear as chips next to the icon in the header. Remove a chip to clear that rule, or clear filters from the drawer.
  • Filter choices stay in sync with the Test Cases list for this project. Changing or clearing filters refreshes the sidebar and selects the first matching test case.

Assigning Assignees

On project Test Cases you can assign one or more Assignees. These are project users associated with the test case. When you later add the test case to a Test Cycle, assignees can be inherited as Testers for that case if they are members of the Section Team. Final tester assignment is still managed in the Test Cycle.

From the Test Cases list

  • In list view, find the Assignee column. Hover the cell and click Edit assignees (pencil).
  • In the Assignees popover, search by name, email, or role, then select one or more project users.
  • Use Clear all to remove everyone, or Save to apply the selected assignees.

From the Overview tab

  • Open a test case and go to Overview. Use the Assignee field to add or change assignees the same way.

Bulk update

  • Select multiple test cases, click Assignee on the bulk bar, choose Replace, Add, or Remove, select users, then Apply.

Permissions and limits

  • Editing assignees requires the Edit Assignee privilege on Test Cases. Your role may allow editing only on test cases you created (Own) or on all cases (All).
  • Assignee assignment is available on project test cases. It is not available on master Test Cases in the Testcase Library.

Note:  Assigning Assignees on a test case is not the same as Assign Testers inside a Test Cycle. Cycle testers are set when you build or edit the cycle; test case assignees only help pre-fill eligible testers.

8. Linking Test Cases to Requirements

Linking connects a test case to the requirement it verifies. This supports traceability and reporting.

  1. From the row menu, choose Link Requirement.
  2. Select the Phase from the drop down.
  3. Select Requirement (or use the requirement picker).
  4. Save the link.
  5.  

Template special field mandatory_requirement_link (default on) can require a requirement before publish (and on create when Phase is active). Published test cases must be converted to Draft or Reviewed before you can change links.

At the template level, Mandatory Requirement Link on the Test Cases module Condition tab controls whether a test case must be linked to a requirement before it can be published. See image below.

9. Import and Export

Download (export)

  • Toolbar Download – export selected or available test cases (privilege export-test-cases; Read or Read and Edit can download).
  • Row Download — export a single test case file (such as Excel) when permitted.
  •  
  •  

Import Test Cases (ZIP/Excel)

  1. Click Import Test Cases (ZIP/Excel). The dialog title is Import Test Cases. The current UI is Update existing (create/update toggle temporarily disabled). Upload ZIP or .xlsx (max 20 MB); Excel filenames must match Test Case IDs (for example TC0000001.xlsx). Download sample test case Excel template when needed.
  2. Upload the ZIP or Excel file containing your test case data.
  3. Map spreadsheet columns to BriefSpec fields (Next: Mapping), then Import.
  4. Review the import summary (updated / skipped / errors; Created when create-mode is available) and finish.
  5. To change Test Data or Test Steps on a Published test case (including one already assigned to a Test Cycle) without converting it to Draft in the UI, use the export and re-import update flow in the next chapter.

10. Updating Published Test Cases via Export and Re-Import

Published test cases are locked for normal edit in the application. When you need to change Test Data, Test Steps, or other mapped fields on an existing test case – including a Published case that is already present in a Test Cycle – export the file(s), edit offline, then re-import in Update existing mode. The Test Case ID stays the same; status stays Published; cycle assignment is not removed by this update.

When to use this flow

Use this flow when the test case is already Published (and optionally already on a Test Cycle) and you need content updates without Convert to Draft & Edit. Prefer Convert to Draft & Edit when you are changing status, requirement links, or doing interactive edits in the UI.

Prerequisites

You need export permission (export-test-cases) and import permission (import-test-cases). Work in the same project that owns the test case. Keep each Excel filename equal to the Test Case ID (for example TC0000001.xlsx).

Steps

  1. 1. Open the project sidebar Testing > Test Cases.
  2. 2. Export the test case(s): select one or more rows and use Download on the toolbar to get a ZIP, or use Row Download for a single Excel file when permitted.
  3. 3. Open each exported workbook. Typical sheets: Cover Sheet (title and related fields), Test Data (Field / Value), and Test Steps (Step / Expected Result).
  4. 4. Edit the content you need (Test Data rows, Test Steps / expected results, and any other mapped Cover Sheet fields). Do not rename the file away from the Test Case ID (keep TC0000001.xlsx).
  5. 5. If you updated more than one file, put the .xlsx files into a ZIP. A single .xlsx can be uploaded as-is (the app zips it automatically).
  6. 6. On Test Cases, click Import Test Cases (ZIP/Excel). Confirm the dialog is Update existing test cases (create mode is currently disabled in the UI).
  7. 7. Upload the ZIP or Excel file (max 20 MB).
  8. 8. On the Mapping step, map Cover Sheet fields and whole sheets for Test Data and Test Steps (or the Step / Expected Result columns). Use the sample template if you need a layout reference.
  9. 9. Click Import. Review the summary: updated (success), skipped (for example Test Case ID not found in this project), or errors.
  10. 10. Open the test case (or refresh the list) and confirm Test Data and Test Steps show your changes. Published status and Test Cycle membership remain.

What this update does and does not do

  • Does: replace mapped content such as title (when mapped), objective, prerequisites, Test Data, Test Steps, test case type, and mapped custom fields on the existing Test Case ID.
  • Does not: create a new Test Case ID; change status away from Published; remove the case from Test Cycles; or bypass import/export privileges.

Skipped rows usually mean the filename / Test Case ID does not match a case in this project. Fix the ID or export again from the correct project, then retry.

11. Import Master Test Cases

If your organization uses the Test Case Library under Settings > Project Artifacts Library, you can import pre-built master test case sets into the current project. Use Import from Master Test Cases (dialog: Import Master Test Cases) on the project Test Cases toolbar.

12. Testcase Library (Using Templates)

Under Settings > Project Artifacts Library > Test Case Library, administrators maintain reusable master test case sets (plan test_case_library_module). Authors can import these into a project instead of building every case from scratch. Library Insights indexing for AI reuse is covered in the Test Library Insights guide.

See below the Project Artifacts Library hub and the Test Case Library tile under Settings.

Clicking on the Tile brings up the details below.

Each entry is an instance of a Test Case library import. Click on the Test Case set ID to view the list of Test Cases imported in one of the imports. You will see the details below.

You can click on any of the Master Test Case ids and view its details.

Master Test Cases are view only and can be imported into a Project.

To create a single Master Test Case click on the ‘Create New Master Test Case’ button and fill out the details. AI will generate the Test Case based on the selected inputs and the input prompt.

To import a batch of Test Cases into the library start by clicking on the ‘Add Testcase Library’ icon. You see the screen below.

Upload a ZIP file or a .XLSX file with a set of Test Cases in it. Click Next to enter the Mapping details. The application does an analysis of the uploaded ZIP file.

It then prompts the user to enter key values like Industry, Software, Pillar & Epic.

If you have used the file earlier for upload and wish to skip any duplicate test cases from being imported, then keep the ‘Skip Duplicate’ flag selected.

Enter all the fields and Click on the Next button.

This step allows you to map the fields found in the Excel files with the System fields. AI tries to auto map most of the fields. So, any field where you see “Apply AI suggestion” is a field that can be automatically mapped by just clicking on the field in the Left side. The remaining fields can be mapped using drag and drop. After this step click on Import button.

After importing you see the final result of the import.

User can click on the “Download log” button to view the processing details.

13. AI Features

When AI is enabled for your tenant:

  • New Test Case / Create a Test Case – AI drafts test data and steps from your prompt (Positive/Negative/Boundary/Edge).
  • Generate Test Cases (Phase) – AI bulk generation from multiple requirements (Positive/Negative/Boundary/Edge). May use Library Insights when the project template Generate with Library Insights flag is on.
  • Regenerate – refresh AI content of existing test cases (row or bulk, up to 20; privilege regenerate-test-cases).
  • Master Test Case – AI creates Master Test Case

If AI is disabled, contact your organization administrator. If you exceed AI usage limits, you may see a token limit message—try again later or contact support.

  • Project Dashboard – charts for total test cases, status breakdown (including Reviewed when used), and requirement linkage.
  • Phase – generate test cases in bulk from phase requirements (Generate Test Cases).
  • Backlog — requirements that can feed test case generation.
  • Test Cycles — schedule and run test cases with assigned testers. Test case Assignees can be inherited as cycle Testers when they are on the Section Team.
  • Defects — log issues found during execution; defects can reference a test case.
  • Settings > Project Artifacts Library > Test Case Library – organization-wide master test case sets (if your subscription includes test_case_library_module).

15. Quick Reference Workflow

A typical end-to-end flow:

  1. Define requirements in Backlog or Phase (including from SOW or transcript if used).
  2. Create a Phase and import verified requirements into a Phase.
  3. Generate or create test cases from requirements in a Phase.
  4. Review and edit in Draft (and Reviewed as needed); then Publish when ready for cycles.
  5. To revise Test Data or Test Steps on a Published case already in a Test Cycle: export, edit offline, re-import (Update existing) – see chapter 10.