Documentation improvement request

[jfstephe]

🤔 What's the problem you've observed?

Setting up cucumberjs with a react application is a nightmare.

Should we use --require or --import?
Should we use ts-node? ts-node/esm? babel? tsc? tsx?
What are the magic combination of tsconfig, package.json and NODE_OPTIONS that are needed to get it working?

✨ Do you have a proposal for making it better?

Give at least one example of the above that you know works. Otherwise it's just going to invite developers to duplicate a lot of effort to find out the above

📚 Any additional context?

From my experience, the only one I got working was tsx. The 'test' scenario was a react application created using CreateReactApp, which imports the following troublesome libraries:

rgb-hex@4.1.0 - A pure ESM module
redux-toolkit@1.9.7 - A cjs only library

I also needed to use the following:
tsx
esm-loader-css

With the following config:
package.json
"type": "module"

tsconfig.json (key parts - some may not be needed)
"target": "ES2017",
"module": "esnext",
"moduleResolution": "node",
"allowJs": true,
"allowSyntheticDefaultImports": true,
"allowArbitrartExtensions": true",
"isolatedModules": true
"include": [
"src/**/*"
]

cucumber.mjs (key parts) - NOTE: use REQUIRE NOT IMPORT
require: ["src/test/setup.ts", "src//*.steps.ts", "src//*.steps.tsx"]
requireModule: ["global-jsdom/register", "tsconfig-paths/register"]

NODE_OPTIONS="--loader tsx --loader esm-loader-css"

Issues:
ts-node - didn't work with rgb-hex as doesn't seem to be able to convert node_module packages
babel - close but again couldn't get it to work with rgb-hex as doesn't seem to be able to convert node_module packages (Note that JEST gets around this with this)

---

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

[jfstephe]

Also, FYI this was on node 18.14.2

[davidjgoss]

This is not something we'll have documentation for in cucumber-js - event just the React ecosystem has virtually infinite different combinations of structure and dependencies, all of which is a moving target, even before we get to any other ecosystems.

Happy to look at adding a basic example to https://github.com/cucumber/cucumber-js-examples though.

[jfstephe]

Sure. I get where you are coming from. I think it's probably a simpler set of combinations though. (happy to be wrong)

For example cucumber can be used client or server side. Assuming the project under development is either commonjs or esm, it could have commonjs and/or esm dependencies.

I just don't think (and I'd be very happy to be wrong here) that babel and ts-node for example can work in all those scenarios.

Having some guidance to say, in the scenario of client side Esm project using both commonjs and esm dependencies, to say use TSX and here's a config we know works would be super useful.

[jfstephe]

The cucumber typescript example you linked to is a perfect example of something that works some of the time, but not all of the time for different dependencies. Finding that out leaves you a bit blind sided, and then you have to embark on a nightmare of, in our case, about 10 days dev time to sort out. We came close to giving up on cucumber as a result.

[pixelass]

We just removed cucumber from one of our projects because of this bottomless pit of issues.
We're still using it in our boilerplate but one specific problem with next.js and Satori requires import.meta.url in an edge function and every option in the documentation or issues failed at some point.

I might have done something wrong (which isn't surprising considering the vague docs on how to get ESM with typescript support).
Since everything works except for cucumber, I dare say: "something is fishy here".

This example does not help at all since it doesn't even have a tsconfig 🤷: https://github.com/cucumber/cucumber-js-examples/tree/main/examples/typescript-node

I ❤️ cucumber and use it a lot, just in this one case I had to ditch all behavior tests because they became a show-stopper.

[hynding]

Not sure if this will resolve any of the issues here but thought I'd share a recent comment I made in this closed issue where I got tsx to work without ts-node nor tsconfig-paths with ts module setting ES2022 and npm package type module:

#2403 (comment)

[holgergp]

Plus 1 for adding tsx to the documentation. I have setup cucumberjs countless times using the documented ts-node approach, but it always felt cumbersome to get it up and running.
I am using tsx now in a context where I want to use cucumberjs to test a calculation library (no react, no css). And even in that context this was a breeze to setup, such that I have typescript in my step-definitions/support. I would be happy to provide a PR to add this to the docs.

It boils down to this cucumber.json

{
  "default": {
    "import": ["features/step-definitions/**/*.ts"],
    "parallel": 2,
    "format": ["html:cucumber-report.html"]
  }
}

this package.json

{
  ...
  "scripts": {
    ...
    "cucumber": "NODE_OPTIONS='--import tsx' cucumber-js"
    ...
  },
  "devDependencies": {
    "@cucumber/cucumber": "^11.2.0",
    "tsx": "^4.19.2",
    ...
  },
  ...
}

and this typescript config

{
  "compilerOptions": {
    "target": "ES2017",
    "module": "esnext",
    "strict": true,
    "esModuleInterop": true,
    "allowJs": true,
    "moduleResolution": "Node",
    "resolveJsonModule": true
  }
}