debugging.md

🐛 Debugging

Command

error.command contains the file and arguments that were run. It is intended for logging or debugging.

error.escapedCommand is the same, except control characters are escaped. This makes it safe to either print or copy and paste in a terminal, for debugging purposes.

Since the escaping is fairly basic, neither error.command nor error.escapedCommand should be executed directly, including using execa() or parseCommandString().

import {execa} from 'execa';

try {
	await execa`npm run build\ntask`;
} catch (error) {
	console.error(error.command); // "npm run build\ntask"
	console.error(error.escapedCommand); // "npm run 'build\\ntask'"
	throw error;
}

Duration

try {
	const result = await execa`npm run build`;
	console.log('Command duration:', result.durationMs); // 150
} catch (error) {
	console.error('Command duration:', error.durationMs); // 150
	throw error;
}

Verbose mode

Short mode

When the verbose option is 'short', the command, duration and error messages are printed on stderr.

// build.js
await execa({verbose: 'short'})`npm run build`;

$ node build.js
[20:36:11.043] [0] $ npm run build
[20:36:11.885] [0] ✔ (done in 842ms)

Full mode

When the verbose option is 'full', the subprocess' stdout, stderr and IPC messages are also logged. They are all printed on stderr.

The output is not logged if either:

• The stdout/stderr option is 'ignore' or 'inherit'.
• The stdout/stderr is redirected to a stream, a file, a file descriptor, or another subprocess.
• The encoding option is binary.

// build.js
await execa({verbose: 'full'})`npm run build`;
await execa({verbose: 'full'})`npm run test`;

$ node build.js
[00:57:44.581] [0] $ npm run build
[00:57:44.653] [0]   Building application...
[00:57:44.653] [0]   Done building.
[00:57:44.658] [0] ✔ (done in 78ms)
[00:57:44.658] [1] $ npm run test
[00:57:44.740] [1]   Running tests...
[00:57:44.740] [1]   Error: the entrypoint is invalid.
[00:57:44.747] [1] ✘ Command failed with exit code 1: npm run test
[00:57:44.747] [1] ✘ (done in 89ms)

Global mode

When the NODE_DEBUG=execa environment variable is set, the verbose option defaults to 'full' for all commands.

// build.js

// This is logged by default
await execa`npm run build`;
// This is not logged
await execa({verbose: 'none'})`npm run test`;

$ NODE_DEBUG=execa node build.js

Colors

When printed to a terminal, the verbose mode uses colors.

---

Next: 📎 Windows
Previous: 📞 Inter-process communication
Top: Table of contents