config: support configuration as objects #1952

davidjgoss · 2022-03-09T09:18:41Z

🤔 What's changed?

Support objects as well as argv-style strings in configuration files
- Check them against a schema when loading (kinda the equivalent of what commander does with the argv)
- Validate the final amalgamated configuration against rules e.g. retryTagFilter with retry
Support configuration files being ESM or JSON
- Check for cucumber.mjs and cucumber.json by default
Provide a loadConfiguration function for the new JavaScript API, use it internally and in tests
Rationalise discrete modules for configuration, api, and cli without circular dependencies

This is a big diff, much of it comes from shifting the source of truth for configuration away from the argv/commander stuff inwards a bit, since we can now have configuration coming in object form as well. Also lots of documentation changes!

Out of scope

Support for YAML and environment variables as other configuration mechanisms - we'll likely do these soon though!
Adding an entry point and documentation for the new API - will be covered in the next PR

⚡️ What's your motivation?

Fixes update profile configuration file #751 - solves the long-standing problem of the awkward argv-based configuration file format, but in a backwards-compatible way rather than a whole new concept
Helps with Programmatic API for running cucumber-js #1711 - provides an easy function for API consumers to get the configuration from their user's project

🏷️ What kind of change is this?

🏦 Refactoring/debt (improvement to code design or tooling without changing behaviour)
⚡ New feature (non-breaking change which adds new behaviour)

♻️ Anything particular you want feedback on?

A lot of documentation changes. The intent is to stop everything being talked about in terms of the CLI, and instead cite both config files and CLI as ways to influence things - hence cli.md getting a lot shorter and configuration.md being added. Also added docs for some things that weren't covered previously.

📋 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.

davidjgoss · 2022-03-13T18:35:58Z

features/profiles.feature

@@ -95,3 +98,22 @@ Feature: default command line arguments
  Scenario: specifying a configuration file that doesn't exist
    When I run cucumber-js with `--config doesntexist.js`
    Then it fails
+
+  Scenario: using a JSON file


No real change needed for this to work, because require() works for JSON anyway.

davidjgoss · 2022-03-13T18:36:25Z

cucumber.json

@@ -0,0 +1,20 @@
+{


A good example of what configuration can look like now.

davidjgoss · 2022-03-13T18:37:13Z

src/api/convert_configuration.ts

+    formats: {
+      stdout:
+        [...flatConfiguration.format]
+          .reverse()


reverse because the last one should win if there's several.

davidjgoss · 2022-03-13T18:37:52Z

src/api/index.ts

-export * from './loadSupport'
-export * from './runCucumber'
+/*
+Anything exported here will be publicly available via `@cucumber/cucumber/api`


The entry point and documentation for the API will be in a follow-up PR.

davidjgoss · 2022-03-13T18:42:51Z

src/configuration/check_schema.ts

@@ -0,0 +1,35 @@
+import * as yup from 'yup'


This is essentially doing for object-based configuration what commander does for argv-based configuration - just checks it's the right shape.

davidjgoss · 2022-03-13T18:43:55Z

src/configuration/default_configuration.ts

@@ -0,0 +1,25 @@
+import { IConfiguration } from './types'
+
+export const DEFAULT_CONFIGURATION: IConfiguration = {


This has been effectively refactored out of ArgvParser, because that's no longer the only way we get config.

davidjgoss · 2022-03-13T18:45:30Z

src/configuration/merge_configurations.ts

+  return undefined
+}
+
+export function mergeConfigurations<T = Partial<IConfiguration>>(


This does for object-based configuration what the various helpers on ArgvParser do for argv-based configuration.

davidjgoss · 2022-03-13T18:46:07Z

src/configuration/types.ts

-      }
-    | false
-  options?: IParsedArgvFormatOptions
+export interface IConfiguration {


The set of options supported in both files and CLI.

davidjgoss · 2022-03-13T18:46:55Z

src/configuration/validate_configuration.ts

@@ -0,0 +1,9 @@
+import { IConfiguration } from './types'
+
+export function validateConfiguration(configuration: IConfiguration): void {


Once all configuration is loaded and merged together, here we validate if any options are contradictory - schema conformance is already checked earlier.

davidjgoss · 2022-03-13T18:47:21Z

src/runtime/index.ts

@@ -33,16 +33,6 @@ export interface IRuntimeOptions {
  worldParameters: any
 }

-export const DEFAULT_RUNTIME_OPTIONS: IRuntimeOptions = {


As above, defaulting now handled as part of configuration load/merge/validate.

docs/cli.md

aurelien-reeves

Great work, on both options and documentation! 🤩
A few comments, but it looks really great, well done (as usual 😅)

docs/configuration.md

docs/dry_run.md

src/api/run_cucumber_spec.ts

src/api/types.ts

src/cli/helpers.ts

src/configuration/default_configuration.ts

src/configuration/from_file_spec.ts

Co-authored-by: Aurélien Reeves <aurelien.reeves@smartbear.com>

aurelien-reeves

Great! Looks good to me!

davidjgoss added 30 commits February 23, 2022 21:33

add testing for esm format

dee627a

handle both types somewhat awkwardly

1c533e8

convert to file url (will be needed for windows)

ad9d6f0

Merge branch 'main' into feat/config-import

d265ffd

fix catch clause

010a37f

move some types around

03df338

more moving

a2d9311

start to build out configuration module

764f301

whoops dont need this one

d1f8951

add default config

a7874f8

add todo comment

e0bd615

wip fromFile

59256cf

merge main

c416579

make a start on file loading

a7459f6

progress on profiles and merging

030bbf1

add lodash.mergewith

3caeb64

WIP remove validation from argv parser

3916a65

expand this test a bit

c91efda

a note about strings for later

7ef8db6

moar test

8226f34

more on merge

5c5f3c3

start to rework parser

d519534

remove defaults, fix array merging

799f760

simplify

e4aa809

handle mergeable tag strings

9a5878d

merge json nicely

4a62e10

progress

c6cbf6f

change profile feature to sometimes use objects

17819ca

last argument wins when specifying stdout formatter

a308cff

Merge branch 'main' into feat/config-import

802fe45

simplify config handing in cli

befcd9c

davidjgoss commented Mar 13, 2022

View reviewed changes

cucumber.json

@@ -0,0 +1,20 @@

{

Copy link

Contributor Author

davidjgoss Mar 13, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A good example of what configuration can look like now.

davidjgoss commented Mar 13, 2022

View reviewed changes

simplify typing

27e3c41

davidjgoss commented Mar 13, 2022

View reviewed changes

davidjgoss added 3 commits March 13, 2022 18:58

add changelog entry

5b87d8e

fix typo

ae77a17

whoops

26d6289

davidjgoss marked this pull request as ready for review March 13, 2022 20:03

davidjgoss requested review from aurelien-reeves, charlierudolph and aslakhellesoy March 13, 2022 20:03

aurelien-reeves reviewed Mar 14, 2022

View reviewed changes

docs/cli.md Outdated Show resolved Hide resolved

aurelien-reeves reviewed Mar 14, 2022

View reviewed changes

davidjgoss and others added 5 commits March 14, 2022 10:29

add --force-exit alias for --exit, rename property on object

1aeb7ef

single source of isTruthyString

397cc9d

correct wrong format name

73c5fa4

Co-authored-by: Aurélien Reeves <aurelien.reeves@smartbear.com>

remove pointless reindent

1a3cbd3

add tests for other formats in from_file_spec.ts

280d694

aurelien-reeves approved these changes Mar 14, 2022

View reviewed changes

davidjgoss merged commit f7419e0 into main Mar 15, 2022

davidjgoss deleted the feat/config-import branch March 15, 2022 08:14

travi mentioned this pull request Mar 21, 2022

use new profile config format form8ion/cucumber-scaffolder#534

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

config: support configuration as objects #1952

config: support configuration as objects #1952

davidjgoss commented Mar 9, 2022 •

edited

davidjgoss Mar 13, 2022

davidjgoss Mar 13, 2022

davidjgoss Mar 13, 2022

davidjgoss Mar 13, 2022

davidjgoss Mar 13, 2022

davidjgoss Mar 13, 2022

davidjgoss Mar 13, 2022

davidjgoss Mar 13, 2022

davidjgoss Mar 13, 2022

davidjgoss Mar 13, 2022

aurelien-reeves left a comment

aurelien-reeves left a comment

		@@ -0,0 +1,25 @@
		import { IConfiguration } from './types'

		export const DEFAULT_CONFIGURATION: IConfiguration = {

		@@ -0,0 +1,9 @@
		import { IConfiguration } from './types'

		export function validateConfiguration(configuration: IConfiguration): void {

config: support configuration as objects #1952

config: support configuration as objects #1952

Conversation

davidjgoss commented Mar 9, 2022 • edited

🤔 What's changed?

Out of scope

⚡️ What's your motivation?

🏷️ What kind of change is this?

♻️ Anything particular you want feedback on?

📋 Checklist:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aurelien-reeves left a comment

Choose a reason for hiding this comment

aurelien-reeves left a comment

Choose a reason for hiding this comment

davidjgoss commented Mar 9, 2022 •

edited