Modular Tests in Jira: Compose Reusable Manual Steps With Xray Cloud

A checkout scenario often repeats the same product-selection and basket checks as several other manual tests. Copying those steps into every case creates separate definitions to review when the workflow changes. A shared module can reduce that duplication, provided its starting conditions and expected outcomes still make sense in every caller.

For modular tests in Jira, Xray Cloud provides Call Test steps: a manual Test can include another manual Test within its own step sequence. During execution, Xray expands the called steps into the Test Run. This is app-provided test composition, not a native Jira feature or automatic execution of the application. The procedure below describes the documented Cloud workflow; no Jira or Xray configuration, test creation, import, or execution was performed for this example.

Choose Composition Rather Than Another Reuse Mechanism

Use composition when the repeated unit is an ordered interaction with its own checks. The parent retains the larger scenario, while a Call Test step references a reusable Test. An independently useful module can also be executed on its own when its required setup is supplied.

Parameterization addresses a different change: the procedure stays the same while inputs or expected values vary. Xray Cloud allows parameterized called Tests and call-context values, so composition and parameterization can coexist. A Call Test reference determines which steps participate; parameter values determine the data those steps use. Do not turn a need for another input into an unnecessary nested workflow.

Test Sets and repository folders organize definitions. A Test Set is a flat collection of Tests; repository folders provide hierarchical organization at the Space level. Putting two Tests in a Test Set or the same folder does not insert their steps into a third Test. A Test Execution supplies an execution context, rather than replacing the parent's structural definition.

Define Modules That Can Stand Alone

A reusable name is not enough to make a useful module. Decide what the module proves, which state it requires, and what state it leaves for the next part of a scenario. Those decisions let a reviewer assess both standalone use and composition without guessing hidden dependencies.

Check Access and the Manual Test Boundary

The Modular Tests reference limits this design to manual Tests. Keep both the parent and its called building blocks within that boundary; do not assume that Cucumber or Generic definitions can be mixed into the same mechanism. Confirm that the installed Cloud app exposes the documented controls. The public documentation is not proof of your tenant's feature rollout, configuration, or plan entitlement.

For company-managed Spaces, Xray's permissions guide associates editing Test Details with Jira's Edit Work Items permission. Viewing a Test and being allowed to edit it are different checks. Verify access to the intended parent and each called definition, and obtain creation permission if new Tests are needed.

Execution has separate requirements. The execution guide requires Browse and Resolve permission on the Test Execution, and neither the Test nor Test Execution may have a workflow status configured to disallow execution. A read-only execution page does not establish permission to run or change results. Resolve these prerequisites with the administrator before attempting an authorized setup.

Specify the Entry and Exit Contract

Give each module complete actions, data and observable expected results. A basket-check module might require a prepared shopper basket, then verify its contents and persistence after refresh. It is independently executable if its own setup explains how the required basket is supplied and verified; it need not depend on another Test having happened to run first.

In the parent, review each handoff separately. An earlier module's expected end state must satisfy the next module's starting assumptions. Sharing a signed-in session does not by itself prove the right account, basket contents, address, or environment. Preserve every condition that affects the result, including negative conditions such as an empty basket or no additional lines.

Add Call Test Steps in the Parent

Once the definitions and their contracts are approved, the current Cloud documentation describes this route in the Test issue's steps area:

1. Open the intended parent Test with Test Steps and confirm that it is manual.
2. Open the Add Step dropdown and select Call Test. The issue-selection modal opens.
3. Select the intended existing manual Test through the dropdown. Check the displayed key and summary against the approved module, rather than selecting a similarly named case without inspection.
4. Click Add. The Modular Tests guide says the new reference is added immediately as a Test Step and appears in purple.
5. Place ordinary steps and Call Test references in the intended scenario order. The Test Steps guide documents dragging, arrow controls and Change Rank for reordering steps. Clear an active step search first, because it disables creating, reordering and cloning.
6. Review the resulting sequence and persistence boundary. When using Edit in Dialog, its outer Save commits the dialog's changes; do not assume finishing an individual step edit saves the whole dialog. Reopen the definition to confirm the intended references and order.

The editor's compact Call Test reference is not the full execution script. Step content can be expanded or collapsed for inspection, but the execution expansion is a separate view of the run. Keep the module's identity visible during review so a useful summary cannot conceal selection of the wrong Test.

Resolve Setup and Nesting Before Execution

The most consequential setup limitation is explicit: Xray ignores Precondition Issues associated with Tests when those Tests are called or included in another Test. A module's standalone Precondition therefore cannot be treated as inherited setup in the parent. Nothing about a Call Test reference proves that the application has been prepared.

Put the parent's initial requirements in its own preconditions and make necessary setup or verification explicit in its manual procedure. For later calls, establish the required state through preceding actions and check their expected outcomes. If a required account, fixture or environment is unavailable, stop for human review under the team's policy rather than recording an invented application result.

The current reference states a depth limit of five called Tests and gives the chain A → B → C → D → E. It also states a total limit of 200 called Tests for a Test Run. Keep the documented chain as the boundary reference instead of inferring an extra level from informal language about parents and children. A shallow design is easier to inspect, but the limit is a product constraint, not a target to fill.

The call-context dataset does not support multiple iterations. That restriction belongs beside any plan to combine nested manual tests with input variation; the existence of parameters does not establish an arbitrary loop at each call. The documentation reviewed here does not establish the exact rejection behavior for self-calls or circular references. Keep the authored call graph acyclic and resolve such behavior separately, rather than promising a particular warning or recursion safeguard.

An Unexecuted Checkout Composition

The following single versioned packet is fictional. It gives each module a standalone setup contract while making the parent's initial setup and intermediate basket state explicit. The labels identify this explanation only; they are not vendor-observed records or live Jira keys.

Shared Fixture and Operational Unknowns

MODULAR-26v1 is one fictional, UNEXECUTED checkout-review design. ScenarioParent, CatalogModule and BasketModule are authored labels, not real Jira keys. All three are assumed Manual Tests using Action, Data and Expected Result fields, not an import payload. The shared fixture is a nonproduction shop with a signed-in approved test shopper, an available product named Cedar Notebook, a saved delivery address, and checkout review enabled. No real account, dataset, Test, Call Test step or Test Run has been created or changed. Actual configuration, permissions, selected definition versions, approvals, imports and execution results are Unknown / NOT RUN.

CatalogModule

CatalogModule is independently executable when the shared fixture is ready and the shopper starts with an empty basket. Its own declared Precondition is that shared fixture and empty basket; a standalone executor must arrange and verify them. CatalogModule step C1: Action = Open the Cedar Notebook product page; Data = Cedar Notebook; Expected Result = The product name is Cedar Notebook and the product is available. CatalogModule step C2: Action = Add the product to the basket; Data = Quantity 1; Expected Result = The basket contains Cedar Notebook and its quantity is 1. This module performs no checkout or order submission.

BasketModule

BasketModule is independently executable when the shared fixture is ready and its basket has exactly one Cedar Notebook with quantity 1 and no other lines. Its own declared Precondition is that shared fixture and seeded basket; a standalone executor must arrange and verify them without relying on CatalogModule having run. BasketModule step B1: Action = Open the basket; Data = The prepared shopper basket; Expected Result = Exactly one line is displayed and its product is Cedar Notebook and its quantity is 1. BasketModule step B2: Action = Refresh the basket page; Data = The same shopper session; Expected Result = Exactly one line remains and its product is Cedar Notebook and its quantity remains 1. This module performs no checkout or order submission.

ScenarioParent

ScenarioParent explicitly requires the shared fixture and an initially empty basket as its own Precondition. Parent step P1: Action = Open the shop home page and inspect the shopper and basket; Data = The approved test shopper; Expected Result = The intended shopper is signed in and the basket is empty. Parent step P2: Call Test = CatalogModule. Parent step P3: Call Test = BasketModule. Parent step P4: Action = Continue to checkout review without submitting an order; Data = The same shopper and saved delivery address; Expected Result = The review screen is displayed and Cedar Notebook has quantity 1 and the saved delivery address is displayed. Calls stay in this order. CatalogModule C2 supplies the basket state required by BasketModule; the parent must not assume either called Test's Precondition is inherited or executed. No nested calls occur inside either module. Missing fixture, access or a prerequisite is a proposed Hold for human review, not an invented Xray status or a failed product result.

Expected Expansion and Human Review

The expected structural expansion is P1, CatalogModule C1, CatalogModule C2, BasketModule B1, BasketModule B2, P4, in that order. Preserve each source Test label, original step identity, Action, Data and every conjunct of its Expected Result. The Call Test references P2 and P3 are replaced by the called manual steps in this explanatory trace; neither called Test's declared Precondition becomes an extra execution step. ScenarioParent's explicit initial setup remains required, and the handoff after C2 must satisfy the seeded-basket assumption before B1.

This is a structural prediction derived from the frozen prose, not an observed Xray expansion, accepted configuration, saved result or application execution. Independent execution of either module would require its own setup and separate Test Run context; no standalone run is implied by seeing its steps in the parent's run. Actual step statuses, actual results, synchronization, version choice and human approval remain Unknown / NOT RUN. Hold is an authored review decision only. No product operation, import, order submission or release decision is authorized by this example.

Expanded Position	Source Test / Step	Action and Data	Expected Result
1	ScenarioParent / P1	Open the shop home page and inspect the shopper and basket. Data: The approved test shopper.	The intended shopper is signed in and the basket is empty.
2	CatalogModule / C1	Open the Cedar Notebook product page. Data: Cedar Notebook.	The product name is Cedar Notebook and the product is available.
3	CatalogModule / C2	Add the product to the basket. Data: Quantity 1.	The basket contains Cedar Notebook and its quantity is 1.
4	BasketModule / B1	Open the basket. Data: The prepared shopper basket.	Exactly one line is displayed and its product is Cedar Notebook and its quantity is 1.
5	BasketModule / B2	Refresh the basket page. Data: The same shopper session.	Exactly one line remains and its product is Cedar Notebook and its quantity remains 1.
6	ScenarioParent / P4	Continue to checkout review without submitting an order. Data: The same shopper and saved delivery address.	The review screen is displayed and Cedar Notebook has quantity 1 and the saved delivery address is displayed.

The table is an expected structural trace, not a list of passed steps. In particular, it adds no login, fixture-creation or Precondition step that the packet did not specify. Before a future authorized run, a person must accept the shared setup and the C2-to-B1 handoff. If either is unknown, retain the proposed Hold for review; do not translate that decision into an undocumented Xray status.

Inspect the Expanded Run Without Rewriting History

For a separately authorized execution, the documented entry point is the Test Execution issue's Test Runs tab and the play icon on the intended row. Xray's Modular Tests guide says execution unfolds the called steps. The step-number column indicates when a step belongs to another Test issue and lets the tester navigate to that Test. Use that source indicator to inspect module boundaries as well as the overall order.

Compare the expanded script with the approved parent and module definitions before relying on it. Check the actual actions, supplied data and every expected-outcome clause. In this illustration, seeing Cedar Notebook alone would not satisfy a check that also requires exactly one line and quantity 1. A structurally correct expansion still says nothing about whether the application produced those outcomes.

Record real observations only during authorized testing. The execution guide provides step-level Actual Result, comments, defects, evidence and status, and explains that step-status changes affect the execution status. Do not copy the documentation screenshot's sample results into a new run. Likewise, a called module's presence in the parent's expanded script is not evidence that the module has a separate successful standalone run.

Review change impact before editing a shared module. A change in starting state, action order or expected outcome can make several parents unsuitable even when the shared Test remains well written. Identify the affected scenarios and have their owners review the revised contracts; do not equate reuse with automatic approval.

Keep current definitions separate from execution history. Xray's execution guide says Test Runs copy definitions and are not automatically updated when the Test definition changes. It describes Reset and Merge as explicit operations with different effects, including loss of saved execution information on reset. The precise selection and refresh behavior of a called module's versions in a particular tenant still needs verification. Do not promise that a module edit rewrites every historical run, and do not reset or merge evidence merely to make a display look current.

Start with one parent and a small pair of independently useful modules. Approve their setup and handoff conditions, inspect the expanded expected results, and resolve missing prerequisites before anyone records an outcome. Expand the reuse pattern only when another tester can understand the complete scenario without relying on the original author's memory.