add ability to enable debug logging

[davidjgoss]

🤔 What's changed?

Adds the ability to enable debug logging for Cucumber. This is done one of two ways:

• For regular CLI users, setting DEBUG=cucumber as an environment variable (leaning into the common https://www.npmjs.com/package/debug library)
• For JavaScript API consumers, adding debug: true to the environment object (an argument in all the API functions)

As part of this, solidified the "logger" concept which is currently internal but will be exposed to plugins eventually. Previously it was a Console instance pointed at the stderr stream. It essentially still is, but it's behind a facade with just debug, error and warn methods. The thinking here is to reinforce that we should not be emitting lots of stuff, unless something is wrong or we have debug on, and that reporting is the domain of formatters.

⚡️ What's your motivation?

It's hard to troubleshoot your setup in Cucumber. People regularly raise issues or try to get help from the community and it's hard to tell whether it's a bug or misconfiguration. Often it comes down to an experienced contributor spotting something, or a lot of back and forth to get to the bottom of an issue.

The debug logging added here is initially focused around configuration, since that's very much low hanging fruit for troubleshooting, but will be expanded in time to cover more stuff.

Another side of this problem is to emit warnings when things look like they might be configured wrong; that's valuable but out of scope here.

🏷️ What kind of change is this?

• 🏦 Refactoring/debt/DX (improvement to code design, tooling, documentation etc. without changing behaviour)
• ⚡ New feature (non-breaking change which adds new behaviour)

♻️ Anything particular you want feedback on?

Since the debug package is Node.js-specific, I've kept it towards the outside of the code, in the CLI. Also I thought JavaScript API consumers would want to be able to control debug logging regardless of environment variables, as some frameworks have their own kind of options for this.

📋 Checklist:

• I agree to respect and uphold the Cucumber Community Code of Conduct
• I've changed the behaviour of the code
  • I have added/updated tests to cover my changes.
• My change requires a change to the documentation.
  • I have updated the documentation accordingly.
• Users should know about my change
  • I have added an entry to the "Unreleased" section of the CHANGELOG, linking to this pull request.

---

This text was originally generated from a template, then edited by hand. You can modify the template here.

[coveralls]

Coverage increased (+0.02%) to 98.253% when pulling c10e8d4 on feat/debug into 7298f30 on main.

[davidjgoss]

An example of what comes out of this for a fairly typical project:

Configuration will be loaded from "cucumber.js"
No profiles specified; using default profile
Resolved configuration: {
  backtrace: true,
  dryRun: false,
  forceExit: false,
  failFast: false,
  format: [
    'rerun:@rerun.txt',
    'message:dist/cucumber.ndjson',
    'json:dist/cucumber.json',
    'html:dist/cucumber.html'
  ],
  formatOptions: {},
  import: [],
  language: 'en',
  name: [],
  order: 'defined',
  paths: [],
  parallel: 0,
  publish: false,
  publishQuiet: true,
  require: [ 'support/**/*.ts' ],
  requireModule: [ 'ts-node/register' ],
  retry: 0,
  retryTagFilter: '',
  strict: true,
  tags: '',
  worldParameters: {}
}
Found feature files based on configuration: [
  '/Users/davidgoss/Projects/my-project/features/adding.feature',
  '/Users/davidgoss/Projects/my-project/features/editing.feature',
  '/Users/davidgoss/Projects/my-project/features/empty.feature'
]
Found support files to load via `require` based on configuration: [
  '/Users/davidgoss/Projects/my-project/support/CustomParameters.ts',
  '/Users/davidgoss/Projects/my-project/support/CustomWorld.ts',
  '/Users/davidgoss/Projects/my-project/support/delegates/BrowserDelegate.ts',
  '/Users/davidgoss/Projects/my-project/support/hooks.ts',
  '/Users/davidgoss/Projects/my-project/support/index.ts',
  '/Users/davidgoss/Projects/my-project/support/pages/TodosPage.ts',
  '/Users/davidgoss/Projects/my-project/support/steps/steps.ts'
]
Found support files to load via `import` based on configuration: []