Skip to content

Latest commit

 

History

History
95 lines (68 loc) · 4.45 KB

DEBUGGING.md

File metadata and controls

95 lines (68 loc) · 4.45 KB
Raw

Debugging at Orval

There are several methods available for debugging the Orval codebase.

Running the Development Environment

The first step when working with the project is to set up the development environment. After following the setup instructions in the CONTRIBUTING.md file, you can use the default command yarn dev to run the codebase locally. This command is part of the turbo dev process and will run the sample project located at react-query/basic. You can use this sample as a starting point to debug the output generated by the project.

If you'd like to try debugging a different sample, feel free to update the generate-api script in the package.json file to reference a different sample or modify the existing react-query/basic sample as needed.

Once your environment is set up, the only remaining step is to configure your IDE to allow for breakpoint debugging. This will enable you to step through the code and inspect specific areas of interest.

Below is an example configuration for Visual Studio Code that you can add to your launch.json file:

{
  "type": "node",
  "request": "launch",
  "name": "Run Dev Server",
  "runtimeExecutable": "yarn",
  "args": ["dev"],
  "skipFiles": ["<node_internals>/**"],
  "console": "integratedTerminal",
  "internalConsoleOptions": "neverOpen",
  "env": {
    "PATH": "${workspaceFolder}/node_modules/.bin:${env:PATH}" // This ensures VS Code references the project's local packages
  },
  "cwd": "${workspaceFolder}"
}

Debugging with Tests

Another approach to debugging is by writing and running tests. This is especially useful if you want to isolate specific pieces of code and evaluate their performance without delving into the entire codebase.

Testing can be more complex than running the development environment, as it requires a thorough understanding of the interfaces and functions you aim to test. However, once familiar with the codebase, this approach becomes highly effective for targeted debugging.

To implement this, create a test file adjacent to the code file you want to test. For example, if you're working on operation.ts, you would create a corresponding test file named operation.test.ts.

Benefits of this approach:

  1. It improves the overall codebase by adding test coverage.
  2. It allows you to test isolated pieces of the code, making the debugging process more predictable.

To run these tests in your IDE, you can use the following configuration in Visual Studio Code:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Current Test File",
  "runtimeExecutable": "yarn",
  "args": [
    "test",
    "${file}" // Refers to the currently open file in the editor
  ],
  "skipFiles": ["<node_internals>/**"],
  "console": "integratedTerminal",
  "internalConsoleOptions": "neverOpen",
  "env": {
    "PATH": "${workspaceFolder}/node_modules/.bin:${env:PATH}" // This ensures VS Code references the project's local packages
  },
  "cwd": "${workspaceFolder}"
}

Note for Windows users: You may need to adjust the cwd path to include the specific package directory, such as "${workspaceFolder}/packages/core".

Troubleshooting

1. Undefined function when running the generate command?

Due to the monorepo structure, debugging the entire flow at once can be challenging. To simplify the process, try mocking some of the packages or breaking the flow into smaller, more manageable parts.

You can also extract the parameters passed to the function, create fixtures with those values, and import them as JSON files to test changes in isolation.

2. Missing dependencies like TSC or Vitest?

This error occurs when your IDE is unable to locate the necessary binaries in node_modules. It usually means you need to configure your IDE to reference the local node_modules folder. Use the following environment variable to resolve this issue:

"env": {
  "PATH": "${workspaceFolder}/node_modules/.bin:${env:PATH}"
}

3. Tests not found in the launcher?

This issue often arises in a monorepo structure because the test runner cannot locate the correct path. To fix this, specify the package path in the cwd field as shown below:

"cwd": "${workspaceFolder}/packages/{package-to-reference}"

This is especially common on Windows, where path handling requires more explicit configuration.