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).

Be lazy

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.

Name everything

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

Describe everything

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:

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.

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.

You can run tests in different configurations with ⇢ test sequences and ⇢ run configurations.

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 validations

Testing software is always about comparing a desired to an actual behavior/state. A test case without a ⇢ validation is a test case without purpose.

Use variables

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.

Unused variable

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.

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