Best Practices for Structuring

Follow these tips to improve the quality, maintainability, and collaboration potential of your automation projects.

Before you start

Before finalizing your test structure, align your design with these three core principles:

• Keep it simple: Make structures and modules only as complex as necessary. Apply this to test structures, test cases, modules, everything.
• Keep it logical: Ensure your structural hierarchy reflects your test requirements. Group related actions (like entering credentials and clicking login) and separate distinct workflows.  
• Be lazy: Prioritize reusability. Reuse anything you can.

Clear documentation makes your test suite organized and easier for teams to maintain. Ranorex Studio offers several ways of documenting your test with naming, descriptions, and special reporting actions. 

Undocumented tests are unfinished tests.

Name everything

Give every test container, module, repository item, and data connector a descriptive name. Use naming conventions and avoid using default names, as they make collaboration difficult.

1. Test suite with only default names. Confusing, extremely hard to maintain, a nightmare for collaboration
2. Test suite with good names for all items. You can see what everything does at a glance

Describe everything

Add detailed descriptions to items within the Test suite view. These descriptions appear automatically in the Report, providing clarity for stakeholders.

1. Double-click in the Description column next to an item.
2. Enter your text in the editor. You can use formatting and images to add context.

Examples of descriptions for different items

Test suite description editor:

Add manual reporting actions

Add specialized actions to make your reports more informative:

• Capture screenshot: Use this action to insert an image at specific points in your test, even if no error occurs.
• Log: Insert custom messages or technical data into the report to explain complex steps.
  

A test case represents a primary function of your test, like adding entries to a database. Smart folders are for further structuring of test cases. Note that only Test cases count toward the success diagram in the final Report.

1. Not ideal: Using a smart folder as the primary test container, with the test case as a subitem.
2. Ideal: Test case as the primary test container, with smart folders as subitems for structuring.

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. If your requirements are too complex for a single suite, consider moving functionality into separate projects or solutions. This allows you to keep test suites simpler, which also keeps maintenance manageable and collaboration feasible.

For more information, see Structures and How to Choose One.

Ensure that test cases do not depend on the success or data of a previous test case. Independent tests are easier to troubleshoot and allow for more flexible execution configurations.

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.

1. Access to test sequence configuration (possible if the project contains 2 or more test suites).
2. Test sequence configuration.
3. Run configuration selection per test suite.

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 instead of constant values in modules to make them reusable and your test more flexible.

1. Constant strings for two values set as part of the module
2. 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.

1. Unused variable.
2. The variables’ default values.

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

1. Ideal: the data source is assigned to the test container that contains the bound variable.
2. Avoid assigning the data source to test containers farther away, like these two.

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:

1. The test container only executes a part of the data source based on a condition.
2. It’s better to remove the condition and adjust the data source so it only contains the data required.

1. Here, we have a test case where descendant structures are executed only if conditions are fulfilled.
2. 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.