A checkout test, an order-history test, and a stock-reservation test may all need familiar setup, but they rarely need exactly the same starting state. Copying the same login and stock-reset paragraph into every case makes those differences harder to maintain. One edit can leave several cases describing an outdated account or fixture.
Xray Cloud Preconditions let you define shared conditions and associate them with the Tests that need them. The reusable object belongs to the installed Xray app, rather than being a native Jira test-management feature. A useful shared definition says what must be true before testing begins. Associating it with a Test does not log a user in, restore a database, or prove that the required state exists.
Start with a condition that multiple Tests genuinely share. “An active shopper is authenticated with permission to place an order” describes a required state. “Enter the username, submit the login form, and check the account page” describes actions used to establish or test that state. Keeping the two separate makes it easier to decide whether a failed setup blocks the intended check or is itself the behavior under test.
Make the definition specific enough to inspect. Identify the account role, relevant fixture characteristics, and the state that the tester should observe. Use approved references to test data rather than putting passwords or other secrets into a shared work item. A summary such as “Setup complete” leaves each reader to invent the missing conditions.
Split conditions when Tests need them independently. Xray's documentation uses authentication and database restoration as examples of setup that can be reused separately or together. For a checkout workflow, an authenticated shopper and available stock can be separate Preconditions. An order-history Test might need only the shopper, while a stock-reservation Test might need only the stock baseline.
If the reusable content is an action sequence, consider whether it belongs in test steps or a called manual Test instead. Xray Cloud's modular Tests can call other Tests and unfold their steps for testers during execution. This is a different reuse mechanism, with an important limitation: Preconditions of Tests being called or included are ignored. Do not assume that calling a login Test also brings along that Test's Preconditions.
This procedure assumes Xray Cloud is already installed and the target Jira space is configured to offer the Precondition work type. If that option is missing, ask the administrator to check the existing setup before proceeding. Creating a similarly named ordinary Jira work item is not a substitute for the app's Precondition object.
The current Xray Cloud guide uses Space and Work Type in its creation instructions. Your Jira interface may use different terminology, so verify the corresponding fields in your tenant rather than following an older Server or Data Center screenshot. The steps below describe the documented Cloud route, not a tenant-specific walkthrough.
For company-managed spaces, Xray's permissions guide lists Browse Spaces for viewing Xray work items, Create Work Items for creation through the standard Jira dialog, and Edit Work Items for Xray-specific fields, including Precondition Details. Team-managed spaces use their own roles and granular permissions. Ask the administrator to check your access to both the Precondition and the intended Tests if viewing, editing, or association is unavailable. Do not assume that permission to create an item grants every later operation.
Before authoring, identify the Tests that should consume the shared definition and inspect their types. This prevents a broadly named setup item from collecting unrelated cases that happen to mention the same environment.
Use a summary that describes the required state, such as “Active shopper authenticated for checkout.” Avoid naming it after one consumer if other Tests will reuse it.
Open Precondition details and inspect the type before adding the shared content or associating Tests. The documented built-in types are Manual, Generic, and Cucumber. The type overview says that the Precondition and Test types must have the same Kind; the association instructions state that only Tests of the same Type will be associated. For a straightforward setup, use the same built-in type on both sides. Do not assume that arbitrary custom types are interchangeable.
Treat a type change as a potentially destructive operation, even while preparing a new item. Xray documents a confirmation step and warns about information and association loss. Establish the intended type before investing in the definition, and review any existing content or links before changing it.
For a Manual example, write a concise, observable condition in the available definition area. The current editing guide refers to Steps within Precondition details: hover over the field, edit it, and use the check icon to save. It separately describes editing Description and saving that field with Save. The presence of a field named Steps does not establish that Xray will perform those actions against your application.
Keep the shared definition narrow. State that the shopper is active and authenticated, then leave the checkout-specific actions and expected results in the checkout Test. If the account must have a special role for only one case, either make that requirement explicit in that case or define a separate condition with a clear scope.
Use the Precondition's own Tests section to make the relationship explicit. This documented route lets you select existing Tests rather than creating duplicate cases merely to attach setup information.
Xray documents a success message and the associated Tests appearing on the work item. Review the resulting list rather than treating a click or message as proof that every intended case was associated. The same section also offers New test, which is a separate route for creating a Test, not the choice for attaching an existing one.
After association, someone still has to establish and check the required state. A tester may authenticate the account manually, or an approved external setup process may prepare the fixture. The relationship in Xray documents the dependency; it does not demonstrate that either activity happened.
The following association plan is fictional and unexecuted. All keys, application states, and Test names are illustrative. The types are deliberately matched so that the example does not depend on an undocumented cross-type association.
Check | Required State and Type | Intended Tests | Review Before Reuse |
|---|---|---|---|
Signed-In Shopper | PRE-10: an active shopper is authenticated (Manual) | TEST-20 checkout and TEST-21 order history (Manual) | Confirm the account role and session are suitable for both tests. |
Stock Baseline | PRE-11: the fictional product has reservable stock (Manual) | TEST-20 checkout and TEST-22 stock reservation (Manual) | Keep stock-reset actions separate from the required starting state. |
API Stock Fixture | PRE-12: the API stock fixture exists (Generic) | TEST-30 API stock read (Generic) | Check the fixture with the external setup process; a link does not create it. |
Saved Address | PRE-13: the shopper has a saved address (Cucumber) | TEST-40 saved-address checkout (Cucumber) | Check compatible types without assuming a UI association runs automation. |
TEST-20 needs both the authenticated shopper and reservable stock. TEST-21 reuses the shopper condition without inheriting an irrelevant stock requirement. TEST-22 uses the stock condition without requiring the same shopper session. This keeps each Test's prerequisites visible without turning every setup variation into a copied paragraph.
The Generic and Cucumber rows illustrate compatible associations only. They do not specify an automation framework, fixture job, generated feature file, or execution order. Those implementation choices require their own supported workflow. Before running any case, check the actual required state instead of inferring readiness from the table or from the number of associations.
Shared setup concentrates maintenance in one definition, so changes deserve a review of every intended consumer. Separate a change to the meaning of the condition from a change to its Xray type; the documented risks are different.
Suppose the shopper condition changes from a standard customer to an account with an additional purchasing permission. Open the associated Tests and check whether that state still fits each purpose. The order-history case may need an ordinary account, while checkout may require the new permission. Keeping the old broad association would conceal a meaningful difference.
As a team convention, record which Tests should keep the revised condition and which need a separate definition. Do not assume that editing shared text automatically removes unsuitable links, updates historical executions, preserves a snapshot, or performs a complete impact analysis. The association list is a starting point for review, not proof that the revised setup remains valid everywhere.
When an association is no longer appropriate, the documented removal route is the ellipsis menu on the relevant Test row in the Precondition's Tests table, followed by Remove and Confirm. Review the selected relationship carefully; removing an association is a different intention from deleting a Test work item.
Changing a Precondition's type is not a safe way to make one existing definition serve every test technology. Xray's current Cloud guide says that changing the type loses the previous information details and the associated Tests. The documented flow opens a modal after selecting the new type and requires Confirm.
Before anyone confirms such a change, record the existing definition, current type, and intended associated Test keys through your team's approved review process. Decide whether a separate Precondition of the required type would preserve the original consumers more clearly. Creating another definition can be preferable to disrupting a shared Manual condition merely to accommodate a Generic Test.
If a type change is approved, review the resulting information and associations against that recorded intent. Look specifically for expected relationships that are now missing, and rebuild only the associations that are still appropriate and compatible. Do not treat the warning as a promise of automatic conversion, a reversible migration, or guaranteed restoration of the previous setup.
A reusable Precondition is useful when a reviewer can answer three questions: what state is required, which Tests depend on it, and who or what establishes it before execution. The shared definition answers the first question and the association list helps with the second. The third still belongs in the team's actual preparation and execution process.
For the fictional checkout case, verify that the intended shopper session is active and that stock is available before starting the checkout assertions. If setup is missing, follow the team's execution policy rather than recording a successful checkout result. If login behavior itself is the target of the Test, keep its actions and expected results explicit instead of hiding them inside an assumed starting state.
Begin with one narrow shared condition and a small, reviewed set of compatible Tests. Keep setup actions separate, inspect the resulting associations, and review every consumer when the definition changes. Before changing a type, stop at the documented warning and assess the information and relationships you could lose.
A green automated test history can help a developer identify a safe-looking change while leaving a QA lead unable to answer a different question:…
A checkout test appears under Payments, again in a Smoke folder, and once more under the latest release. When the payment rules change, someone…
A Jira story is Done, a test case is linked, and the related bug is Closed. Can the release owner conclude that the story's…
Create traceable test cases, prepare release-specific test runs, and keep approved coverage current as the product changes.
