Best practices for structuring
On this page, you’ll find tips on how to structure your tests for better quality, maintainability, troubleshooting, and collaboration.
On this page
Three principles of test design
Follow these principles to get tests that are well structured, easy to maintain, and more efficient – regardless of test size or complexity.
Keep it simple
As simple as possible, as complex as necessary. Apply this to test structures, test cases, modules, everything.
Keep it logical
Your structures, test cases, modules, etc. should make sense in terms of your test requirements. Don’t split up items unnecessarily (e.g. having username/password input and clicking a “Log in” button in two different modules). Don’t mix things that should be separate (e.g. putting an entire webshop end-to-end workflow in one module).
Reuse anything you can. Always make reusability a priority.
Document your test
Ranorex Studio offers several ways of documenting your test with naming, descriptions and special reporting actions. These may seem unnecessary at first, but good documentation keeps your test suite organized, greatly increases maintainability, and makes it much easier to work in teams.
Undocumented tests are unfinished tests.
Always give your test containers, modules, repository items, data connectors, etc. good names. When working in teams, use naming conventions. Default names are okay in the short term, but never in the long term.
Test suite with only default names. Confusing, extremely hard to maintain, a nightmare for collaboration
Test suite with good names for all items. You can see what everything does at a glance
In the test suite view, you can add descriptions to the test suite itself, test containers, and modules. Descriptions are also automatically included in the report, making it easier to understand.
To add descriptions:
Double-click in the description column next to an item.
An editor opens that offers various formatting options. You can even include images.
Some examples of descriptions for the different items:
Test suite description editor
In the report
Test container description editor and report view
Add manual reporting actions
With the Capture screenshot and Log actions, you can add images and messages to the report manually. They can make the report easier to read, especially for other people who may not be as familiar with the test structure.
Add Capture screenshot actions
Ranorex Studio normally only includes screenshots in the report if an error or a failure occurred. With the screenshot action, you can insert screenshots at any point, e.g. to show which UI element an action was performed on.
Add Log actions
Ranorex Studio already documents test runs quite extensively, but sometimes, you may want to include additional information. You can do so easily with the Log action.
Don’t leave items empty/deactivated
A finished, working test suite should not have empty or deactivated items in it. Empty items are okay if they’re not yet finished. Deactivating items is okay to show they still need work or for troubleshooting.
Deactivated recording module
Empty smart folder
Deactivated teardown region
Use the test case as the primary test container
Test cases represent a primary function of your test, like adding entries to a database. Smart folders are for further structuring of test cases.
In the technical sense, the main difference between test cases and smart folders is that only test cases are counted in the success diagram in the report. This reflects the role of test cases as the primary test container.
Not ideal: Using a smart folder as the primary test container, with the test case as a subitem
Ideal: Test case as the primary test container, with smart folders as subitems for structuring
Avoid deep test suite structures
As a general rule, you should avoid going deeper than 5-6 test container levels. Remember: Keep it simple.
Complex test requirements may seem like they make complex test suite structures necessary, but that’s not entirely true. On the ⇢ previous page, we described different test structure types and how you can use projects or even solutions to move away from a test suite-based structure. This allows you to keep test suites simpler, which also keeps maintenance manageable and collaboration feasible.
Keep test cases independent
When possible, test cases should not depend on other test cases. This makes troubleshooting and running tests in different configurations easier.
One way to do so is by using ⇢ setup and teardown regions for test suites and test containers. It’s a best practice to have test cases wrapped in at least one setup/teardown region.
Access to test sequence configuration (possible if the project contains 2 or more test suites)
Test sequence configuration
Run configuration selection per test suite
Use variables instead of constant values in modules to make them reusable and your test more flexible.
Constant strings for two values set as part of the module
Replacing them with variables makes the module reusable
Maintain your variables
Regularly clean up your variables and delete unused ones. Make sure all variables have sensible default values. This is important when values from a bound data column can’t be retrieved, like when running a recording module directly and not as part of a test suite.
The variables’ default values
Keep data sources close to where they’re used
Assign data sources or parameters as close to the test containers where they’ll feed values to variables. At worst, a data source should be no more than 2 test container levels away from where it’s used.
The descendants of a test container inherit its data sources. However, over several levels, it gets quite hard to tell what is going on.
With data-driven testing in general, it’s less the amount of data you feed into the test, but rather the quality that determines whether you’ll get significant results. The data should cover as many different test scenarios as possible.
Ideal: the data source is assigned to the test container that contains the bound variables
Avoid assigning the data source to test containers farther away, like these two
Think twice before using conditions
Sometimes, conditions are necessary, but often, they can be avoided with a different test container structure.
Conditions increase complexity, make maintainability worse, and are often an issue in collaboration. This is especially true when conditions extend over several test container levels. At worst, conditions should extend over no more than 2 nested test container levels.
Here are two examples:
The test container only executes a part of the data source based on a condition
It’s better to remove the condition and adjust the data source so it only contains the data required
Here, we have a test case where descendant structures are executed only if conditions are fulfilled
We can replace this by splitting up the test case into two separate ones and replicating the structure with test containers that are always executed