Debugging Business Central Tests with AL Test Runner


  1. Install the Test Runner Service app (see; direct download of the app file from here) or use the “Install Test Runner Service” command from VS Code to install into the Docker container specified in the config file
  2. Set the URL to the test runner service in the testRunnerServiceUrl key of the AL Test Runner config file
  3. Define a debug configuration of request type ‘attach’ in launch.json to attach the debugger to the service tier that you want to debug (should be the same service tier as specified by the testRunnerServiceUrl key)


From v0.4.0 of the AL Test Runner app it is possible to debug Business Central tests without leaving Visual Studio Code. There’s a lot of scope for improvements but if you’re interested in trying it out it’s included in the marketplace version now.

Test Runner Service App

This is a very simple app that exposes a codeunit as a web service to accept a codeunit ID and test name to run. Those values are passed to a test runner codeunit (codeunit isolation) to actually run the tests. This is so that the tests are executed in a session type of WebService which the debugger can attach to (the PowerShell runner creates a session type of ClientService).

The app is in the per tenant object range: 79150-79160 to be precise (a number picked pretty much at random). If that clashes with some other object ranges present in the database you can clone the repo and renumber the codeunits if you want. The source is here:

You can use the Install Test Runner Service command in VS Code to automatically download the app and install into the container specified in the AL Test Runner config file.

The app is not code signed so you’ll need to use the -SkipVerification switch when you install it.


A new key is required in the AL Test Runner config file. This specifies the OData endpoint of the test runner service that is exposed by the Test Runner Service app. The service will be called from the VS Code terminal – so consider where the terminal is runner and where the service is hosted.

We develop against local Docker containers so the local VS Code instance will be able to access the web service without any trouble. If you develop against a remote Docker host make sure that the OData port is available externally. If you use VS Code remote development remember that the PowerShell session will be running on the VS Code server host.

The url will be in the format:

http[s]://[BC host]:[OData port]/[BC instance]/ODataV4/TestRunner?company=[BC company]

for example against a local Docker container called bc with OData exposed on the default port of 7048 and a company name of CRONUS International Ltd.:

"testRunnerServiceUrl": "http://bc:7048/BC/ODataV4/TestRunner?company=CRONUS%20International%20Ltd."

Debug Configuration

You will need a debug configuration of type attach in the launch.json file. This should attach the debugger to the same service as identified by the testRunnerServiceUrl key. breakOnNext should be set WebServiceClient. Currently UserPassword authentication is the only authentication method supported.

    "name": "Attach bc",
    "type": "al",
    "request": "attach",
    "server": "http://bc",
    "serverInstance": "bc",
    "authentication": "UserPassword",
    "breakOnError": true,
    "breakOnRecordWrite": false,
    "enableSqlInformationDebugger": true,
    "enableLongRunningSqlStatements": true,
    "longRunningSqlStatementsThreshold": 500,
    "numberOfSqlStatements": 10,
    "breakOnNext": "WebServiceClient"


Codelens actions will be added at the top of test codeunits and before each test method. Set a breakpoint in the test method that you want to debug or allow the debugger to break on an error.

Clicking on Debug Test (Ctrl+Alt+D) will attach the first debug configuration specified in launch.json and call the web service to run the test with the Test Runner Service app.

Attaching the debugger and running a test from VS Code

Step in/out/over as usual. When the code execution has finished if an error was encountered the error message and callstack will be displayed in the terminal.


There are some limitations to running tests in a web service session. Most importantly TestPage variables are not supported. There may also be some differences in the behaviour of tests in web services and the PowerShell runner.

7 thoughts on “Debugging Business Central Tests with AL Test Runner

  1. Hi James,
    It seems like we can’t cumulate Run Test and Debug Test ? We need to comment breakOnNext config launcher, otherwise we can’t just run a test.

    Thank’s for this extension.



      1. Hi,
        When I set debug configuration, then I’m able to debug a test.
        But if I just want to run a test (not debug it), I need to reconfigure the launch.json, otherwise I can’t simply run it.
        So my question is: Is there a method to avoid changing configuration ?


  2. Hi James,
    Thank you for your VS Code Extension. It’s very useful! 🙂

    I tried to get debugging tests working as well, but I keep running into the following error:

    {“error”:{“code”:”Authentication_InvalidCredentials”,”message”:”Web service call failed because user could not be authenticated or authorized. CorrelationId: 5d8e2b0a-d42a-47d9-823e-2b373a8c28f0.”}}

    Do you have any idea what might be the problem here and how this could be resolved?


    1. Hi Rob,

      I’m glad that you are finding it useful 👍

      Looks like the extension isn’t able to authenticate with the test runner service. Some things to check:

      – The test runner service extension is installed in the container (download from GitHub or you can install with the command in VS Code if you are running VS Code on the Docker host machine)
      – The testRunnerServiceUrl is correct in the AL Test Runner config.json file
      – OData is enabled on the service tier
      – You can connect to the OData service using the same credentials that are used to run the tests (must be NavUserPassword authentication)

      Hope that helps. If not, let me know what your setup is i.e. are you running the container locally or on a remote box? If VS Code running on the same box as Docker or not?


Leave a Reply to Rob van Bekkum Cancel reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s