Run, test, and debug

Run an application#

Create a Gleam configuration under Run → Edit Configurations. Select the package root and task, then choose Erlang or JavaScript. For JavaScript, choose the runtime installed on your machine. Run the configuration and inspect its console; the command should execute in the selected package, not another workspace package.

Run tests#

Use a gutter test action or create a test configuration. Results appear in the native test runner with package, module, and test nodes. Select a failure to navigate to its source, then rerun that test or the failed set. Test timings help identify slow cases.

The test runner uses an isolated shadow package. If a test behaves differently from a terminal run, compare target, runtime, environment, package root, and compiler version first.

Debug a JavaScript target#

1. Use Gleam 1.16 or later and enable source maps in gleam.toml:

[javascript]
source_maps = true

2. Select the JavaScript target and configure a compatible JavaScript debug adapter through LSP4IJ.
3. Set a breakpoint on executable Gleam code and start Debug.
4. When paused, inspect variables, stack frames, and watches; step through the Gleam source.

Rebuild after source-map changes. A breakpoint in a branch that never executes will not pause the program.

Export a BEAM escript#

With Gleam 1.17 or newer, select the escript-export task in a Gleam run configuration. Confirm the package and output options before running it. This produces an application for the BEAM runtime; JavaScript debugger settings do not apply to that export.