Skip to content

Latest commit

 

History

History
76 lines (49 loc) · 3.86 KB

installation.md

File metadata and controls

76 lines (49 loc) · 3.86 KB
Raw

Installation

With npm:

$ npm install @cucumber/cucumber

With Yarn:

$ yarn add @cucumber/cucumber

Invalid installations

If Cucumber exits with an error message like:

You're calling functions (e.g. "Given") on an instance of Cucumber that isn't running.
This means you have an invalid installation, mostly likely due to:
...

This means you have an invalid installation.

Unlike many libraries, Cucumber is stateful; you call functions to register your support code, and we keep that state until it's used in the test run. Therefore, it's important that everything interacting with Cucumber in your project is interacting with the same instance. There are a few ways this can go wrong:

Global installation

Some libraries with a command-line interface are designed to be installed globally. Not Cucumber though - for the reasons above, you need to install it as a dependency in your project.

We'll emit a warning if it looks like Cucumber is installed globally.

Duplicate dependency

If your project depends on @cucumber/cucumber, but also has another dependency that itself depends on @cucumber/cucumber (maybe at a slightly different version), this can cause the issue with multiple instances in play at the same time. If you're familiar with React, this is a lot like the "invalid hook call" issue.

This is common where you have split some of your support code (e.g. step definitions) into a separate package for reuse across multiple projects, or are perhaps using a third-party package intended to work with Cucumber.

You can diagnose this by running npm why @cucumber/cucumber in your project. You might see something like:

@cucumber/cucumber@8.4.0 dev
node_modules/@cucumber/cucumber
  dev @cucumber/cucumber@"8.4.0" from the root project

@cucumber/cucumber@8.3.0 dev
node_modules/my-shared-steps-library/node_modules/@cucumber/cucumber
  dev @cucumber/cucumber@"8.3.0" from my-shared-steps-library@1.0.0
  node_modules/my-shared-steps-library
    my-shared-steps-library@"1.0.0" from the root project

In this case, the fix is to change the library so @cucumber/cucumber is a peer dependency rather than a regular dependency (it probably also needs to be a dev dependency). This will remove the duplication in the host project. If you don't control the library, consider using overrides (npm) or resolutions (Yarn) to get it down to a single instance.

Deprecated package

When looking at the duplicate dependency issue, it's worth checking whether anything in your project is depending on the old, deprecated cucumber package. Anything touching Cucumber should be using the newer @cucumber/cucumber package.

Linking

With the shared library example above, even if you have @cucumber/cucumber correctly defined as a peer dependency, you can still hit the issue if you hook up the library locally using npm link or yarn link when developing or testing.

This is trickier to deal with. If you run npm link ../my-project/node_modules/@cucumber/cucumber from the library, this should work around it (assuming my-project is your host project's directory, and it's adjacent to your library in the file system).

Notes

In earlier versions of Cucumber, this issue would present with a more cryptic error (the causes and solutions are the same):

TypeError [ERR_INVALID_ARG_TYPE]: The "from" argument must be of type string. Received type undefined
    at validateString (internal/validators.js:125:11)
    at Object.relative (path.js:1162:5)
    ...