The AL Test Runner extension for Visual Studio Code makes it easier to write and run automated tests in your AL apps for Microsoft Dynamics 365 Business Central. Read the intro blog post here. Or, you can watch an overview video just here…
Various development scenarios are supported by the extension including:
- Development against a local Docker container i.e. when you are developing on the Docker host machine
- Development on a remote machine using Remote Development in VS Code
- Development on a local machine for deployment to a Docker container running on a remote machine
Open a test codeunit in VS Code and run one of the following commands:
- Run current test (Ctrl+Alt+T) – the test which the cursor is currently in will be executed
- Run tests in the current codeunit
- Run all tests (Ctrl+Shift+Alt+T)
- Debug current test (Ctrl+Alt+D) – the current test will be run by a custom test runner codeunit via a web service call and the debugger attached to that session (more about debugging here)
The selected tests will be executed against your Docker container and the results shown in the output window. Test methods are decorated according to the latest result (passing, failing, untested). When tests fail the line which caused the failure is highlighted and the error message and callstack can be seen by hovering over the method name or failing line.
The output window will show the file path and line number of failing tests so that you can jump to the test definition (Alt + Click).
The style of the test method decorations and the failing line highlight can be configured.
Pre/Post Test Commands
Set PowerShell commands to be executed before/after tests are executed with Pre Test Command and Post Test Command.
These could be useful for:
- Preparing the test suite in BC14 with the test codeunits and methods that need to be executed e.g. like this
- Unpublishing apps after the tests have been run
The commands will be executed on the VS Code host (the local machine unless you are using Remote Development) but you can use the functions in the ALTestRunner module to invoke a command on the Docker host (see below). Multiple commands can be executed when separated by a semicolon.
Search for “AL Test Runner” in the Extensions sidebar in Visual Studio Code to download and install the extension.
Use the Open Config File command to open the JSON config file.
Most of the required settings will be populated automatically when tests are run or you will be prompted to enter them.
If you are using NavUserPassword authentication in the container you must specify the user name and password to authenticate with. You will be prompted to enter these when running tests. Alternatively they can be entered with the Set Container Credential command.
If there are multiple Business Central companies in the target container you will be prompted to select the correct company to execute the tests in.
If you are running tests in Business Central 14 you will be prompted to enter the test suite name that contains the test(s) to run. Note: in this case the test codeunits and methods must already be populated in the test suite before running the tests. (From Business Central 15 tests are automatically populated on the AL Test Tool page before they are run).
Remote Docker Host
If you are publishing your apps to a remote Docker host then the dockerHost key must be populated with the name of the host. Leaving this key blank implies that Docker is hosted on the local machine.
When using a remote host you may also need to specify the credentials that are used to authenticate with the host. These credentials can be set with the Set VM Credential command.
AL Test Runner will use PowerShell’s New-PSSession command to open a new remote PowerShell session to the host. You must be able to create a session with this command before you will be able to execute tests against a remote host. Credentials can be passed to New-PSSession by populating the VM Credential (as above). Any other options which must be passed to New-PSSession can be specified in the newPSSessionOptions key.
Separate to the config file, AL Test Runner has several configuration options which can be set through VS Code. They can either be applied globally or just to the current workspace.
- Decorate Test Methods – determines whether test methods are decorated according to the last test result
- Failing / Passing / Untested Test Color – defines the decoration colour for each result in RBGA format
- Highlight Failing Line – determines whether the line which caused a test to fail is highlighted
- Failing Line Decoration – the CSS style to decorate the failing line with
- Publish Before Test – whether to publish the extension to the container before executing tests (select between None, Rapid application publish or Publish)
- Test Codeunit Glob Pattern – the glob pattern which identifies test codeunits in the workspace. This is used to determine the filename of failing codeunits. By default all .al files in the workspace are searched. For large projects this might perform badly and a more precise glob pattern should be set e.g. **/Tests/*.Codeunit.al matches only files ending in .Codeunit.al in a Tests folder
- Pre Test Command / Post Test Command – a PowerShell command to execute before and after tests have been executed
The ALTestRunner module will be imported into the al-test-runner terminal that is opened in VS Code when tests are executed. It will be imported when pre/post test commands are executed. Some functions that might be useful in that context are listed below.
- Get-ALTestRunnerCredential returns a PSCredential object with the credentials to authenticate with the container. Add the -VM switch to return credentials to authenticate with the Docker host
- Get-ContainerName returns the name of the container for both local and remote hosts
- Get-DockerHostSession returns the PSSession object used to execute commands against the remote host
- Get-ValueFromALTestRunnerConfig return the key value specified by KeyName from the AL Test Runner config
- Get-ValueFromAppJson return the key value specified by KeyName from the app.json file
- Get-ValueFromLaunchJson return the key value specified by KeyName from the app.json file
- Invoke-CommandOnDockerHost takes a script block to execute on the Docker host