Open up `const { Cli } = require('@cucumber/cucumber')` for programmatic usage

[nicojs]

Is your feature request related to a problem? Please describe.
I'm in the process of adding support for cucumber-js in StrykerJS, the mutation testing framework for JavaScript and friends. See stryker-mutator/stryker-js#2970

I would like to use cucumber programmatically. In fact, I'm already doing that in the MR. However, I realize that I'm using an undocumented API, which I don't like doing, since the implementation could break in a patch release version. I strive to use public APIs only.

Describe the solution you'd like

Would you accept a PR that documents the use of the Cli class for public usage?

const { Cli } = require('@cucumber/cucumber')

I would add it to your docs directory. Either in a new file (programmatic-usage.md) or add it to the cli.md file.

Describe alternatives you've considered

Additional context
In order to make mutation testing feasible, we need a programmatic API. Simply calling childProcess.exec to execute cucumber-js would work, but is terrible for performance since Stryker will run cucumber-js many times during a mutation testing run.

[aurelien-reeves]

You are not the only one using the internal APIs for a programmatic usage.

I think it would be a good idea to stabilize such an API and to document it.

@cucumber/cucumber-js what do you think?

[davidjgoss]

Hey @nicojs, your timing is impeccable! I'm writing a proposal for a new programmatic API this morning that hopefully will be of benefit to you. I'll tag you there as it would be great to get your initial feedback.

[davidjgoss]

Going to close this as we're having a good discussion over on #1711 about a new API to solve this need.

I'll just add that the intent is to leave the Cli class working the way it is in 8.0.0, even though it's not on the public API, to give developers time to switch to the new API and iron out any issues there.

[OhadR]

another use case:

we have AWS env on VPC with very limited access from outside. I would like to have a cucumber on this env for tests. So i wrapped my cucumber project in a docker and deployed it on that VPC. it works like a charm but it is very cumbersome to invoke the tests - you have to enter the docker and run the test by npm test. It could be great to expose a port to that docker, and be able to invoke the tests calling that API