Make your life easier with modules

When you create your tests do you notice that they contain steps you have to repeat over and over, like logging in, setting up test data, navigating to a deep page, or cleaning up after the test? Instead of recording the same “log in as admin” steps in twenty different tests, you can record it once as a module and then reuse it wherever you need it. When the test runs, AIVA executes the module exactly as if those steps were written directly in the test.

Three kinds of modules

AIVA has three types of modules:

• Authentication modules — for all the different ways users log in to your app. An authentication module’s flow must start with a Navigate to URL action. This is the classic “log in once, reuse everywhere” module.
• Generic modules — reusable blocks of steps you can run anywhere in a test, not just at the start (for example, setting up test data or navigating to a deep page). You create a generic module by extracting a range of steps from an existing test in edit mode — generic modules can’t be created from scratch on the new-module page. A generic module can be re-recorded only if its flow starts with a Navigate to URL step; without one it has no standalone entry point, so re-recording (and running it on its own) is unavailable.
• Teardown modules — clean-up steps that run at the end of a test, even if the test failed, for example deleting the user or the data the test created, so your app returns to a known state. A teardown module’s flow must start with a Navigate to URL action, so you can also re-record it and run it on its own. See Clean up after a test with teardown modules.

Whichever kind you use, AIVA executes the module’s steps at test time exactly as if they were written directly in the test.

Modules keep your tests short, clean, and easy to maintain — change the module once (e.g., your login flow changes slightly) and every test that uses it automatically gets the update.

Add a module to a test

A module of either type is referenced by a Run module step. In a test’s edit mode, use the insert (+) menu and choose Module to drop a Run module: <name> step wherever the flow can continue from that point. The step is shown inline among the test’s other steps, with a link to open the module itself. You can expand the step to see the module’s nested steps, both in the test detail and in the test result, including the detailed module result. While the test runs, the module steps expand automatically so you can follow the progress.

Teardown modules can’t be placed anywhere in the flow: they always sit at the end of the test, after all its other steps. See Clean up after a test with teardown modules.

You can also replace a Run module step with a different module from the step’s detail panel — this works for all three types of modules.

There are two convenience shortcuts that create the referencing step for you:

• Creating a test with an authentication module seeds the Run module step for you.
• In edit mode, or from the test result, you can extract a range of steps into a new module; the extracted steps are replaced in place by a Run module step referencing it. In the extraction dialog, you choose the type of the new module. If you choose Teardown and the extracted steps don’t start with a Navigate to URL step, you enter the starting URL there.

For now, a module can’t contain another module, so a teardown module can’t contain an authentication module either. See Known limitations.

Module variables

A module has its own variables, each with its own default value — for example a login module with username and password. The module and the test that uses it keep their variables apart: a test variable is not passed into the module just because it has the same name. Instead, every Run module step decides, for each variable of its module, where the value comes from.

You set this in the Module variables section of the Run module step’s detail panel in edit mode. The same section appears when you insert a module during recording, and as Authentication module variables when you create a test with an authentication module.

Three ways to supply a module variable

	Module default	Fixed value	Bind to a test variable
Value used	The module’s own default	A constant stored on this step	The value of a test variable
Follows changes of the module’s default	Yes	No	No
Can be changed when you start the test, from a batch or the API	No	No	Yes
Use it when	The module’s default is right for this test (the most common case)	This test must always run the module with one particular value	You want to run the same test with different values without editing it

Module default. Every variable starts here when you add a module to a test. The step uses the module’s default value, and if the module’s default changes later, the test follows it. You can’t change the value when you start the test. Variables in this mode are grouped together as N variables use module defaults.

Fixed value. Choose Customize this variable → Set a fixed value and type the value. It is stored on this step only — the module’s default no longer applies to it, and it can’t be changed when you start the test. Mark it as a hidden value for passwords and other secrets.

Bind to a test variable. Choose Customize this variable → Bind to a test variable. The module variable then takes its value from a variable of the test, which you can change for each run — in Run test with custom parameters, in a batch, or through the API. A few things to know:

• By default the test variable gets the same name as the module variable, but you can pick any name, including an existing test variable.
• A new test variable takes its default value from the module at the moment you bind it. From then on it is independent: changing the module’s default does not change it.
• Binding to an existing test variable keeps that variable’s own default value.
• The test variable is shared with every other step that uses it. You can type or assert its value in other steps, or bind several Run module steps to the same test variable.
• If the module variable is hidden, the test variable is hidden too.

Use Reset to module default to return a customized variable to the first mode. When no step uses a test variable anymore, it is removed from the test.

When the module changes

• Replacing the module in a Run module step resets all its variables to module defaults, because the new module has different variables.
• The module drops a variable that a step customizes: the step keeps the setting but marks it as no longer in the module. It has no effect until you remove it or the module adds the variable back.
• Extracting steps into a module: the variables the extracted steps use are copied into the new module together with their default values, and those that no remaining step of the test uses are removed from the test. The new Run module step uses module defaults for all of them. If you want to keep changing them per run, bind them to test variables afterwards.

Running a module on its own

When you run a module by itself, Run module with custom parameters lets you override the module’s own variables for that run.

Tests created before module variable modes

When module variable modes were introduced, existing Run module steps were migrated so that each module variable is bound to a test variable of the same name. A test that already had a variable of that name keeps its value; otherwise the new test variable starts with the module’s default. The tests run with the same values as before, and those values can now be changed for each run. The one difference: these test variables no longer follow later changes of the module’s default — switch a variable to Module default if you want that.

Modules always run their latest version

You never have to “upgrade” a test to a newer module version — a test always runs the latest version of the module at run time. When you edit and confirm a new version of a module, every test that uses it picks up the change automatically on its next run.

On a finished test run, the module step shows which version actually ran:

• latest — the run used the module’s current latest version.
• outdated — the run used an older version than the current latest (older runs keep showing the version they really executed).
• version unavailable — the exact version that ran no longer exists, because the module was later reverted to an earlier version. The step can’t open that version anymore; selecting the module offers to take you to its latest version instead.

Clean up after a test with teardown modules

Tests often leave something behind: a created user, an uploaded file, an order in a cart. Record that clean-up once as a teardown module and attach it to every test that needs it.

• Create or reuse — in edit mode, extract the clean-up steps at the end of a test and choose the Teardown type in the extraction dialog (if the steps don’t start with a Navigate to URL step, you enter the starting URL there), or add an existing teardown module to the test. Each teardown module is referenced by a Run module step, which you can expand, replace, and configure like any other.
• Always at the end — teardown modules are placed after all the other steps of the test. A test can have several of them; they run one after another, in the order you set, and you can reorder them at any time.
• Every teardown runs — AIVA runs the teardown modules even if the test itself failed, and it runs all of them, even if one of them fails.
• Variables — teardown modules have module variables like any other module, so you can pass in the values your test used, for example the email of the user it just created.
• Results — if a teardown fails, the test fails too, with the dedicated status Failed in teardown. You can tell right away whether the problem is in your app or in the clean-up.

Like an authentication module, a teardown module must start with a Navigate to URL step, and it can’t contain another module. Thanks to that starting step, you can re-record a teardown module and run it on its own, like any module that starts with a URL.

Record authentication only once and reuse it

If your tested app requires authentication of the user, your tests will generally all start with a login procedure, with only few exceptions.

If that’s the case, we suggest recording the login procedure as a module and using that module in all tests where it makes sense. This has several advantages:

• You won’t have to re-record the login procedure over and over again, saving time and avoiding mistakes.
• Your tests will be shorter and more readable.
• Should anything change about the login procedure of your app, you will only have to reflect that change in one place, not all the tests.
• In case of test failures, you will easily see whether it was the actual test that failed, or just the login procedure (perhaps indicating simply a wrong password, or the whole application being down).

As with tests, we suggest ending the module with an assertion, so you instantly know if the login itself failed instead of the test that comes after it.