Part of a tester's life is to create mental models of the system under test and use them as simplified abstractions of the real system; we use these models to facilitate discussions and also to perform actual experiments on the system. Certain tools, such as Xray Enterprise Test Case Designer (TCD), assist us in creating representative variations of such models. But then the question arises: how do we create a model in the first place?

The first steps in the “standard” process of creating scenarios in TCD involve identifying variation factors directly from requirements (commonly stories in Jira, maybe UI mockups) and populating the corresponding “Parameters” screen in TCD. But what if the ideas about parameters and values are not easily identifiable and staring at the blank “Parameters” screen does not help? Or if you are not working from requirements in the Story or mockup format?

In this tutorial, we will discuss tips for alternative modeling routes when using TCD.

Gherkin Scripts

Access to most features/screens in TCD requires you to have at least 2 parameters already added to the model. There are two important exceptions - Automate and Forced Interactions.

Let’s imagine we have one or multiple stories with the following acceptance criteria (AC) written in Gherkin.

After reviewing them in Jira, we are not immediately sure which parts could be relevant to our model. The suggested alternative includes the following steps:

1. In TCD, open Automate directly. You need to click on the arrow next to the menu section name (not on the “Scripts” name itself) to open the sub-menus.
   
   
   
   
2. Identify the “full end-to-end flow” based on the acceptance criteria. Copy-paste Gherkin statements into Automate and arrange them in the order of the flow. Understand which steps/events are sequential vs mutually exclusive.
   
   
3. Consistent theme throughout your TCD journey - find the repetitive patterns -> identify what drives the difference. 
   1. For instance, in our AC, the first line is changing because of the type of user, the “When” statement - because of the quantity and types of products.
      
4. For the mutually exclusive steps, include the dynamic elements with the separators.
   1. Bonus points: ask what else could vary, perhaps something you know about the system/flow that is not explicit in AC. Sometimes, variation ideas also remain “hidden” in the story summary/description, without being translated to AC (e.g. mentioning Browser/OS compatibility).

By this step, your compiled Scenario block in TCD Automate could look something like this. You do not have to include quotation marks, they just help with the visual highlight.

Thus, we have identified the TCD parameter value candidates - those dynamic elements from step 4. Now we can go back to the Parameters screen and copy-paste the value lists. With that foundational block ready, we can proceed with Rules/Scenarios. Replace the separated lists in Scripts with parameter names (e.g. “<UserType>” instead of “guest, registered, VIP”).

A few extra considerations:

• Iteration is important - do not worry about identifying all the key variation factors from the first try. Feel free to put placeholder values to facilitate feedback (e.g. “TBD” value for ProductType above).
  
  
• When the whole step/line of the Acceptance Criteria is changing completely and the variants are mutually exclusive, you can choose to parameterize the whole step (like we did above) or create separate Scenario blocks via {[]} filtering (e.g. {UserType[VIP]}).
  
  
• If you already have a small set of Cucumber tests in Xray that follows this kind of pattern but would not benefit as much from TCD optimization, you may still find helpful tips for maximizing efficiency in this tutorial (Cloud; DC).
  

Flow Diagrams

If process flow diagrams are the requirements format we work from, at a high level, we can take the following steps in order to create a TCD model:

1. Identify the start and the key decision point (commonly a diamond-shaped element with the largest number of connections - both incoming and outgoing).
1. If there are multiple decision points with the same number of connections, you can pick the one furthest from the start point.
2. In some formats, the decision points may not have their special designated shape. You will need to focus on the areas where the flow of the diagram branches into multiple paths and understand what triggers the split.
   
   
2. Identify the major outcome(s) tied to the elements from step 1.
   
   
3. Along the path from the start to the key decision point to the major outcome(s), find the biggest "cluster of diamonds" (with 2 or more outgoing paths each) that represents sequential, preferably unconditional steps in the flow.
1. Beware of the diagram types where diamonds are positioned as a sequence but actually represent mutually exclusive choices. The example below would most often be represented in TCD as 1 parameter with 3 values, not 3 parameters with 2 values each.
   
   Image Source
   
4. Identify if other non-diamond paths lead to the same outcomes.
   
   
5. Draft the model for steps 1-4. Typically, you have a parameter per diamond and/or path split with values representing outgoing options. Prioritize the flows of similar length that lead to the selected outcomes
   
   
6. If you feel like you can fit more into the same model (accounting for not only the number of parameters/values but also the complexity of constraints), repeat steps 2-5.

For this tutorial, we will take a purchase order workflow as an example, represented by the diagram below (source):

For step 1, our flow starts from “Submit purchase order” in the top left and the “Tooling in stock?” diamond has 4 total connections (2 incoming “Yes” paths). For step 2, the major connected outcomes are “Ship to customer” and “Scrap parts”. Since they are mutually exclusive, we could opt to focus on only one of them to make the initial model iteration easier - let’s take “Ship to customer”. For step 3, we can make a judgment call on which diamonds belong to the “main cluster” since most of them are located closely together. 

Our analysis so far can be summarized like this:

Now, we can proceed to the initial model draft which could look something like this.

Notice we limit parameter/value selection to keep the scenarios close to the “core” path we have identified. If we are feeling confident, we can add the remaining paths in the second iteration.

A few extra considerations:

• In general, do not expect to fit the entire diagram in one TCD model. It may be easier to handle some of the scenarios outside of the tool or as separate, non-parameterized scripts in TCD. 
• Diagrams that do not have 3+ diamond nodes or split paths may not be a good use case for TCD.
  
  
• Some variation ideas may be specified in the comments for each node rather than explicitly on the diagram, make sure to clarify that (e.g. one rectangle node for “Clean and Pack” does not guarantee there is only 1 type of packaging/shipping you should consider for testing).
  
  
• Keep in mind that sometimes understanding the constraints from just the diagram layout is challenging, especially when analyzing possible connections between non-neighbor elements. For example, if a node has 3 incoming connections and 2 outgoing ones, that does not automatically mean that each incoming path can transition to either outgoing one. Make sure to clarify the relationships.
  
  
• Certain flows allow repeating steps N times; for instance, IVR where a caller can choose an option, then go back to the menu, then choose the option again. For TCD purposes, you will need to define the loop limit that is most common and focus on modeling up to that limit only. Then you can handle lengthier scenarios as standalone scripts or outside of the tool.
  
  

State Transition Tables

If state transition tables are the requirements format we work from, the ability to create a model in TCD depends on the number of states and the variety of possible transitions or events that could lead to transitions. Limited sequential states with 1 possible transition event each are not a good use case.

Overall, the approach requires a parameter per state per transition level. If multiple events can cause the same transition, we would need a parameter per event layer as well. You can guess that the models can become relatively constraint-heavy.

Similar to the recommendations for the flow diagrams, identify the maximum depth of the state transition sequence that you want to represent in the TCD model (including the maximum number of repetitions/loops for the same state). 

Depending on the format of the table, you may need to clarify the exhaustiveness of states and events, mutual exclusivity, and transition precedence rules (if parallel events/states are allowed) before deciding on the most appropriate modeling approach.

For this tutorial, we will take the following abstracted example:

Let’s say the maximum number of loops we want to plan for is 1, which makes our maximum transition flow depth

                     A->B->C->B->C->D->E

Therefore, we need 7 parameters. For the value set of each parameter, ask “what are all the possible states I can transition to from my previous value set?”. The shape of the Parameters screen for this type of modeling often looks “heavier” in the middle. The corresponding draft in TCD could look like this:

In addition to rules controlling each transition possibility between these values, you can leverage either Skip constraints (>>) or extra “N/A” values to represent the scenarios of different length.

Previous Test Cases

Sometimes, the requirements are not yet available or stable enough for you to start designing tests. In order to get ahead, you may choose (or be forced) to leverage the test suites from the previous releases as the main source of information.

Overall, the logic and considerations are similar to the other examples we have discussed so far, remember our consistent theme - find the repetitive patterns, identify what drives the difference. We will cover a few tips for a manual test suite in Excel and an API one in JSON. Analyzing an automated suite in e.g. Java/Cucumber just depends on your comfort with the language, otherwise it is fundamentally similar. 

API/JSON may be the easiest because of the consistent layout and no “extra stuff” - each field of both request and response could be evaluated as a candidate for TCD model inclusion. It depends on how many values it can take and whether its interaction with other fields can meaningfully affect the API function. E.g. fields that trigger extra sections or have conditions against other fields are popular targets. If you have access to the previous/current API data dictionary, it can help double-check your understanding of the request/response structure.

The tricky part about manual test suites is that the variation ideas can be hidden across multiple columns, not just Steps. Commonly overlooked areas are Test Name, Description, Precondition, even Expected Results, and any custom columns for entities related to Test Data. Also, be on the lookout for verbiage inconsistencies, try to take a “zoomed out” approach to map the flow of a group of test cases first, it can help distinguish truly unique elements from the reworded “clones” (similar to “I add items to cart” vs “Products are in the cart” from our AC example).

Once you decompose the existing test suites into TCD parameters and values, you can choose to format them as CSV and leverage Forced Interactions import to kickstart the model (without adding any TCD parameters manually). Accessing the Forced Interactions sub-menu directly requires the same trick - click on the arrow next to the menu section name (“Rules”), not on the name itself.

Conclusion

Model-based testing is a popular technique thanks to its benefits for collaboration, maintenance, and reusability. Models can take various forms, each with its own strengths and drawbacks depending on the use case. To get the most out of the technique, it is important to know the basics of translation from one form to another.

In this tutorial, we shared the selective list of kickstart tips for use cases we often encounter with clients. We hope this guidance will help you get “unstuck” as you explore leveraging Xray Enterprise Test Case Designer in your projects.