A tester needs a repeatable procedure, a product reviewer wants a readable behavior example, and an automation engineer needs to identify an external test. Those needs can describe the same requirement, but they do not call for the same test-definition structure. Choosing a familiar label without checking its underlying kind can leave the next person with the wrong information.
In Xray Cloud, distinguish the name of a Test Type from the structure used to describe the test. Then decide how someone will perform the check and where its actual results will be recorded. Xray supplies these testing concepts through an app for Jira; they are not native Jira test-definition formats. This discussion concerns Cloud documentation, not a promise that Server or Data Center has identical configuration or screens.
Xray's Cloud global settings reference defines three structural kinds: Steps, Gherkin and Unstructured. Its documented mapping connects Manual with Steps, Cucumber with Gherkin, and Generic with Unstructured. A type name is the option authors select; its kind determines the form of the definition.
Test Type Name | Structural Kind | Definition Representation | Choose It When |
|---|---|---|---|
Manual | Steps | An ordered sequence with actions, relevant data and expected outcomes | A tester needs a repeatable procedure and diagnostic detail |
Cucumber | Gherkin | A behavior example expressed in Gherkin statements | Reviewers need shared business-language examples |
Generic | Unstructured | An open-text Definition, such as a charter or an external test identifier | A fixed step sequence does not describe the intended test well |
Do not read that mapping as an exhaustive inventory of every current installation. The global reference lists those three default names, while the current Cloud Test reference additionally lists Exploratory. Xray also documents configurable type options. Check your actual available options and their kinds rather than assuming that a tutorial's default count describes your tenant. The structural comparison remains useful despite that documentation disagreement.
The label also does not establish execution capability. A Cucumber Test can contain Gherkin text without a working automation implementation. A Generic Definition can name an external test without configuring the connection to its runner. Separate the representation decision from the execution and result-collection decisions.
Start with the information the next reviewer or executor needs. A detailed procedure, a business-language example and a free-text definition distribute that information differently. None removes the need for an explicit starting state and a way to distinguish a correct outcome from an incorrect one.
Steps suit a check that benefits from ordered actions and expectations. Xray's Cloud Test Steps documentation describes individual actions with inputs, conditions and expected outcomes, and notes that step fields can be configured. Do not assume that every project exposes an identical set of columns.
Write enough detail for another tester to repeat the intended check without guessing important data or results. “Update the address and verify it” leaves both the change and the expected state unclear. A better procedure names the starting addresses, the requested change and the observations needed after it. Keep incidental navigation separate when a layout change would otherwise force a rewrite of the business rule.
More steps are useful when they isolate meaningful observations, not when they turn every click into a separate assertion. Conversely, combining several outcomes into “works correctly” makes failures difficult to diagnose. Choose the level of detail that lets the executor identify which expectation was not met.
Gherkin organizes an example around context, an event and expected behavior. Given describes the starting state, When names the event, and Then describes the outcome. And can add another condition or expectation. This is useful when product, development and QA need to challenge the same rule before implementation.
Xray Cloud's Gherkin documentation discusses Scenario and Scenario Outline. A concrete Scenario expresses one example; an Outline introduces varying inputs. Select the values because they expose different behavior, not because a table makes it easy to add more rows. For more detail on choosing observable outcomes and avoiding vague steps, see how to write clear Given-When-Then examples.
Authoring remains separate from automation. Cucumber needs matching step definitions that connect the text to implementation code. That implementation needs appropriate data, an environment and assertions. Xray's editor can even save invalid Gherkin with a warning, so saving text is not proof that it is ready to execute. Exporting a feature file likewise does not demonstrate that a runner can perform its steps or that results have returned to Xray.
Unstructured uses an open-text Definition rather than an ordered step schema. The Cloud reference describes different uses: the field can contain an external automated-test identifier, such as a class and method reference, or an exploratory charter. Generic is therefore not a synonym for “automated execution.”
For an exploratory test, describe the mission and relevant risks without pretending that every investigation must follow the same route. For a concise repeatable check, retain the starting state, action and expected result in the text. For an external automated test, make the identifier meaningful to the separately configured integration. A name in a Definition field cannot supply missing implementation or result mapping.
Unstructured describes the storage form, not the quality of the test design. Free text can be precise, and a neatly structured table can still omit the outcome that would expose a defect.
The following fictional packet holds the starting state and required behavior constant. The representations below are design illustrations, not instructions verified against a live application or copyable automation files.
Fictional requirement ADDR-29-v1: An authenticated account has exactly two saved addresses, A and B. A is the only default address and B is not the default. When the user makes B the default address, B must be marked as default, A must no longer be marked as default, and both A and B must remain saved. This requirement has not been executed.
The requirement does not specify confirmation messages, response time, behavior after refresh or sign-out, permissions beyond the authenticated account, or failure handling. Those remain unanswered product questions. Environment readiness, test data access and human approval are pending.
An authored manual plan could express the requirement as follows. These are suggested instructions, not a claim about a fixed Xray field layout:
The final instruction contains several related observations because they jointly define the requested change. A failure to clear A and an accidental deletion of A are different defects, even if B displays the expected default marker in both cases.
The same behavior can be discussed in Gherkin-style wording. Each paragraph below expresses a separate part of the example; it is not a complete feature file or a demonstrated Cucumber execution.
Scenario: Change the default saved address without deleting either address.
Given an authenticated account has exactly two saved addresses, A and B, with A as the only default and B not default.
When the user makes B the default address.
Then B is marked as default.
And A is no longer marked as default.
And both A and B remain saved.Keeping the last two expectations visible prevents a reviewer from approving the example merely because its first Then sounds right. If this later becomes automation, its implementation must assert every required observation. Matching the words to a step definition is not enough if the definition only logs the address state or checks B alone.
A free-text Definition could say: “For an authenticated account with exactly saved addresses A and B, initially only A is default. Make B the default. Expect B to be default, A not to be default, and both addresses to remain saved.” This preserves the same contract without separate structured steps or Gherkin statements.
If the team instead stores an external test identifier here, the referenced implementation must retain that contract. Replacing the explanatory text with a name does not prove that the underlying assertions check both default flags and both saved addresses. Review the implementation and result mapping separately.
These are alternative design representations of the same requirement, not three observed runs. The expected result is conjunctive: B is default, A is not default, and both addresses remain saved. Checking only B would miss an extra default; checking only the default flags would miss an accidentally deleted address.
Execution record: NOT RUN. No browser, Jira tenant, Cucumber runner or external test was executed for this example. Actual results and evidence remain empty; no representation establishes a pass.
A Test's definition is only one part of the workflow. Shared setup, groups of Tests and execution evidence have different responsibilities. Confusing these objects can leave critical expectations outside the material an executor receives.
A Cloud Precondition describes conditions needed before a Test. Xray's introduction requires a matching structural kind, while its association instructions say that only Tests of the same Type are associated. For custom type names, verify actual compatibility rather than assuming that sharing a kind guarantees association. Keep setup such as the initial address state distinct from the action under test, and verify that setup was achieved rather than treating its written description as evidence.
A Test Set is a flat collection used to organize Tests, and a Test can belong to different sets. Adding an address test to a regression set does not change its structural kind or record a result. Organization answers which reusable definitions belong together; execution answers what happened in a particular context.
A Test Run is an internal Xray entity, not a separate Jira issue. Cloud documentation describes a copy of selected specification data, including the relevant steps, Scenario or Generic Definition and associated Precondition details. It explicitly excludes general custom fields, summary and description from that copy. Keep execution-critical expectations in the supported test specification rather than assuming that every Jira field is carried into a run.
Existing runs do not automatically become evidence for an edited definition. The documented update choices can change a run's specification, and resetting can discard recorded results. Review the consequences before updating historical execution data. Also keep the app boundary in mind: Xray Cloud documents its own dedicated database and attachment/evidence storage. A Jira-visible work item does not make all Xray definition and result data ordinary Jira fields or establish a Jira-only backup guarantee.
Changing a label may look less consequential than rewriting a test. The Cloud Test guide warns that changing Test Type loses the previous details and associated Preconditions, and calls the operation permanent and not reversible. Do not use it as a casual way to translate a manual case into Gherkin or turn a charter into a procedure.
Before an authorized change, preserve the reviewed source material through an approved method and identify the intended new definition independently. Compare its starting state, trigger and every expected outcome with the original. Check affected setup associations and execution-history implications separately. Do not assume that cloning, export or history provides a complete recovery route without validating that route for the actual data.
Choose Steps when repeatable procedural detail serves the executor, Gherkin when a behavior example improves shared review, and Unstructured when context-dependent free text or an external identifier is the appropriate definition. Before approving the case, ask another reader to reconstruct the expected result from it. If they lose an address, retain two defaults, invent a success notice or assume an automation run, resolve that gap before the test becomes part of the working baseline.
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.
