ShadowdriverJS Debug Configuration

Overview of Debugging in ShadowdriverJS

ShadowdriverJS can be easily debugged in Visual Studio Code (VS Code) by setting up a proper launch configuration. This allows you to:

Set breakpoints in your test files.
Step through code during test execution.
Inspect variables in real-time for better debugging.
Debug test failures more effectively.

Setting Up Debugging in VS Code

To set up debugging, follow these steps and create a .vscode/launch.json file in your project root with the appropriate configuration:

Example `launch.json` Configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "shadow-runner",
      "program": "${workspaceFolder}/src/shadowRunner/runner.js",
      "args": ["exec", "shadow.conf.js", "--spec", "${file}"],
      "skipFiles": [
        "<node_internals>/**"
      ],
      "env": {
        "NODE_ENV": "development"
      },
      "console": "integratedTerminal"
    }
  ]
}

Explanation of Configuration Properties

type: node: Specifies that the debugger is for Node.js applications.
request: launch: Indicates that this configuration sets up a debugging session.
name: shadow-runner: A descriptive name for your debugging configuration, which appears in the VS Code debug panel.
program: ${workspaceFolder}/src/shadowRunner/runner.js: Points to the location of the shadow-runner.js script that runs ShadowdriverJS tests. Adjust this path according to your project structure.
args: ["exec", "shadow.conf.js", "--spec", "${file}"]: Specifies the arguments passed to the shadowRunner.js. This typically includes:
- "exec": The command to execute.
- "shadow.conf.js": The configuration file used by ShadowdriverJS.
- "--spec" "${file}": Indicates that you are debugging a specific test file. Replace ${file} with the actual path or filename of your test file when you start debugging.
skipFiles: ["<node_internals>/**"]: Skips files in the Node.js internals folder, which helps prevent unnecessary debug output.
env: { "NODE_ENV": "development" }: Sets the environment variable NODE_ENV to development, which is useful for enabling certain features or configurations specific to development mode.
console: integratedTerminal: Uses the VS Code integrated terminal for better output visibility.

Steps to Set Up and Debug

Create the .vscode/launch.json File:
- Open your project in VS Code.
- Navigate to File -> Preferences -> Settings, then search for "launch json" or use the shortcut Ctrl + Shift + D.
- Click on the launch.json file and ensure it is open.
- Paste the provided JSON configuration into this file.
Start Debugging:
- Open the test file you want to debug in VS Code.
- Press F5 or click on the green play button in the debug panel.
- Alternatively, you can right-click on the launch.json configuration and select "Run 'shadow-runner'".

Benefits of Setting Up Debugging

Set Breakpoints: You can set breakpoints anywhere in your test files to pause execution at specific points for inspection.
Step Through Code: Use step-by-step debugging features to inspect variable values, function calls, and more during the execution of tests.
Inspect Variables: View and modify variables on-the-fly without interrupting the flow of the program.
Debug Test Failures: Easily debug failing tests by setting breakpoints and stepping through the code to identify issues.

Example: Debugging a Test File

Suppose you want to debug a test file named example.test.js located in your project directory. Here’s how you would set up and start debugging:

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "shadow-runner",
      "program": "${workspaceFolder}/src/shadowRunner/runner.js",
      "args": ["exec", "shadow.conf.js", "--spec", "example.test.js"],
      "skipFiles": [
        "<node_internals>/**"
      ],
      "env": {
        "NODE_ENV": "development"
      },
      "console": "integratedTerminal"
    }
  ]
}

Start Debugging:
- Open example.test.js in VS Code.
- Press F5 or click the debug button and select shadow-runner.
- The debugger will start, and you can set breakpoints and step through the code as needed.

Overview of Debugging in ShadowdriverJS​

Setting Up Debugging in VS Code​

Example launch.json Configuration​

Explanation of Configuration Properties​

Steps to Set Up and Debug​

Benefits of Setting Up Debugging​

Example: Debugging a Test File​

Further Reading​