Best practices for structuring tests | Ranorex Studio User Guide
Help CenterUser GuideHands-on application topics

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:

    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.

    Note icon

    Note

    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.

    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.

    Note icon

    Note

    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