allow configuration via environment variables

[davidjgoss]

🤔 What's the problem you've observed?

Cucumber can be configured via the CLI and files, but not via environment variables (except the publish functionality which does support some).

This means users that configure most of their other stuff with environment variables often have a sort of frankenstein setup, with some stuff living in the Cucumber config (maybe in profiles) and other somewhat related stuff sitting elsewhere (e.g. in .env files).

✨ Do you have a proposal for making it better?

Support configuring Cucumber via environment variables.

When resolving configuration, each option should be sought from environment variables by converting its key to uppercase-with-underscores format, prefixing with CUCUMBER_OPTION_, and then checking the environment for that key. So for example, retryTagFilter would be expressed as CUCUMBER_RETRY_TAG_FILTER and so on.

TBA on how things like booleans and arrays should be expressed and parsed. We should follow conventions set by other tools if they exist.

Environment variables should take precedence over the configuration file and default, but not over the CLI, which "wins" because it's been passed directly in the command. All options should maintain their current merge vs overwrite behaviour.

Profile-level options are out of scope.

📚 Any additional context?

See conversation on #2346.

---

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

[vitalets]

Do we really need this third source of truth?
Currently if I want some parameter to be configured via env var, I can explicitly define that:

export default {
  retryTagFilter: process.env.MY_VARIABLE_FOR_TAG_FILTER
}

[davidjgoss]

Do we really need this third source of truth?

Need? No. But I think it's worthwhile (if not exactly urgent).

[Ben-EJ]

Mind if I give this a go? : )

[davidjgoss]

@Ben-EJ definitely, feel free to give this a go!

I've just updated the description to clarify a 1) the prefix should be CUCUMBER_OPTION_ to avoid collisions with env vars that we set from Cucumber and 2) the CLI is still top in order of priority.

To give you an idea of where to look, https://github.com/cucumber/cucumber-js/blob/main/src/api/load_configuration.ts#L40-L44 is where the configurations from different places (currently defaults, config file and CLI) are merged together, so capturing from the environment should probably happen around here.

Feel free to drop into #committers-js on the Slack or raise a draft PR if you want some early feedback/guidance!

[0v00]

hey @davidjgoss is this still open to be worked on?

[davidjgoss]

@0v00 sure, let me know if you need any advice.

[0v00]

hey @davidjgoss sorry for the delay, but i should be able to open a PR shortly.

i just want to clarify some behavior - in a situation where we set e.g. CUCUMBER_TAGS="@foo" and also pass in options.provided tag values e.g. --tags "@bar or @baz", what do we want the expected output to be in this case? should we be expecting a merge of values e.g. (@foo) and (@bar or @baz) or should the options.provided values overwrite the ENV values, resulting in (@bar or @baz)? thanks

[davidjgoss]

Sorry for the late reply @0v00!

To your question, yes this should merge and your example is just right. For all config options we should replicate the existing behaviour (either merge or override depending on type), it's just a case of slotting the env-sourced ones in between CLI and config file.

Hope this helps, let me know if you need anything else!