Skip to content

Commit

Permalink
chore: deprecate things from the entry point (#2136)
Browse files Browse the repository at this point in the history
  • Loading branch information
davidjgoss authored Oct 16, 2022
1 parent 7f43644 commit 6081893
Show file tree
Hide file tree
Showing 6 changed files with 109 additions and 27 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CONTRIBUTING.md) on how to contribute to Cucumber.

## [Unreleased]
### Deprecated
- `Cli`, `PickleFilter` and `Runtime` deprecated in favour of new API functions (see [documentation](./docs/deprecations.md)) ([#2136](https://github.com/cucumber/cucumber-js/pull/2136))

## [8.6.0] - 2022-09-20
### Added
Expand Down
57 changes: 57 additions & 0 deletions docs/deprecations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Deprecations

From time to time, we'll deprecate and then remove functionality. This is not done lightly, and is normally a means to help move the project forward in a way that the old functionality is at odds with. We do this in a controlled way, to minimise disruption and give users plenty of time to adapt to the change.

Assuming a current major version of `N`:

1. A minor version (e.g. `N.x.x`) is released with the deprecation. This will normally involve:
- A `@deprecated` comment in our code and types, which IDEs and other tools will recognise
- A runtime warning the first time the deprecated functionality is invoked, where possible
2. Later, a major version (e.g. `N+1.0.0`) is released; the deprecation is highlighted in the release notes
3. Later still, another major version (e.g. `N+2.0.0`) is released with the deprecated functionality removed

## Current deprecations

### `Cli`

Deprecated in `8.7.0`, will be removed in `10.0.0`.

The `Cli` class is used internally to represent an instance of the command-line program invoked via `cucumber-js`. It can be used to run Cucumber programmatically, but is poorly suited for this.

To adapt, pivot to the `runCucumber` function from the [JavaScript API](./javascript_api.md), or raise an issue if you feel your use case isn't catered for.

### `defineStep`

Deprecated in `8.3.0`, will be removed in `10.0.0`.

`defineStep` is a way to generically define a step without tying it to any of the `Given`, `When` or `Then` keywords. This leads to ambiguity in the business language and is considered an antipattern; steps should be clearly applicable to one of those keywords, being a context, action or outcome respectively.

To adapt, review your steps and define them with the appropriate keyword, or just switch to `Given` as a starting point. We're working on adding [an opt-in "strict mode" for keywords](https://github.com/cucumber/cucumber-js/issues/2043) which will yield an error when the keyword in the Gherkin text doesn't match that of the step definition, and could be used to pinpoint such issues in your project.

### `parseGherkinMessageStream`

Deprecated in `8.0.0`, will be removed in `10.0.0`.

`parseGherkinMessageStream` is a way to process a stream of envelopes from Gherkin and resolve to an array of filtered, ordered pickle Ids. Its interface includes internal implementation details from Cucumber which are difficult to assemble.

To adapt, pivot to the `loadSources` function from the [JavaScript API](./javascript_api.md), or raise an issue if you feel your use case isn't catered for.

### `PickleFilter`

Deprecated in `8.7.0`, will be removed in `10.0.0`.

The `PickleFilter` class is used to provide a filter to the `parseGherkinMessageStream` function above.

To adapt, pivot to the `loadSources` function from the [JavaScript API](./javascript_api.md), or raise an issue if you feel your use case isn't catered for.

### `Runtime`

Deprecated in `8.7.0`, will be removed in `10.0.0`.

The `Runtime` class is used internally to represent an instance of the serial test case runner. Its interface includes internal implementation details from Cucumber which are difficult to assemble.

To adapt, pivot to the `runCucumber` function from the [JavaScript API](./javascript_api.md), or raise an issue if you feel your use case isn't catered for.

## Previous deprecations

For deprecations that have been completed (i.e. the functionality removed), see [UPGRADING.md](../UPGRADING.md).
2 changes: 0 additions & 2 deletions src/cli/helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,6 @@ interface IParseGherkinMessageStreamRequest {
/**
* Process a stream of envelopes from Gherkin and resolve to an array of filtered, ordered pickle Ids
*
* @deprecated use `loadSources` instead
*
* @param eventBroadcaster
* @param eventDataCollector
* @param gherkinMessageStream
Expand Down
55 changes: 43 additions & 12 deletions src/index.ts
Original file line number Diff line number Diff line change
@@ -1,17 +1,14 @@
import { default as _Cli } from './cli'
import * as cliHelpers from './cli/helpers'
import * as formatterHelpers from './formatter/helpers'
import { default as _PickleFilter } from './pickle_filter'
import * as parallelCanAssignHelpers from './support_code_library_builder/parallel_can_assign_helpers'
import { default as _Runtime } from './runtime'
import supportCodeLibraryBuilder from './support_code_library_builder'
import * as messages from '@cucumber/messages'
import { deprecate } from 'util'

// Top level
export { default as Cli } from './cli'
export { parseGherkinMessageStream } from './cli/helpers'
export { default as PickleFilter } from './pickle_filter'
export {
default as Runtime,
INewRuntimeOptions,
IRuntimeOptions,
} from './runtime'
export { default as supportCodeLibraryBuilder } from './support_code_library_builder'
export { default as DataTable } from './models/data_table'
export { default as TestCaseHookDefinition } from './models/test_case_hook_definition'
Expand All @@ -38,10 +35,6 @@ export const Before = methods.Before
export const BeforeAll = methods.BeforeAll
export const BeforeStep = methods.BeforeStep
export const defineParameterType = methods.defineParameterType
/**
* @deprecated use `Given`, `When` or `Then` instead; see <https://github.com/cucumber/cucumber-js/issues/2043>
*/
export const defineStep = methods.defineStep
export const Given = methods.Given
export const setDefaultTimeout = methods.setDefaultTimeout
export const setDefinitionFunctionWrapper = methods.setDefinitionFunctionWrapper
Expand All @@ -64,3 +57,41 @@ export const Status = messages.TestStepResultStatus

// Time helpers
export { wrapPromiseWithTimeout } from './time'

// Deprecated
/**
* @deprecated use `runCucumber` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
*/
export const Cli = deprecate(
_Cli,
'`Cli` is deprecated, use `runCucumber` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
)
/**
* @deprecated use `Given`, `When` or `Then` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
*/
export const defineStep = deprecate(
methods.defineStep,
'`defineStep` is deprecated, use `Given`, `When` or `Then` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
)
/**
* @deprecated use `loadSources` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
*/
export const parseGherkinMessageStream = deprecate(
cliHelpers.parseGherkinMessageStream,
'`parseGherkinMessageStream` is deprecated, use `loadSources` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
)
/**
* @deprecated use `loadSources` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
*/
export const PickleFilter = deprecate(
_PickleFilter,
'`PickleFilter` is deprecated, use `loadSources` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
)
/**
* @deprecated use `loadSources` instead; see <https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md>
*/
export const Runtime = deprecate(
_Runtime,
'`Runtime` is deprecated, use `runCucumber` instead; see https://github.com/cucumber/cucumber-js/blob/main/docs/deprecations.md'
)
export { INewRuntimeOptions, IRuntimeOptions } from './runtime'
6 changes: 1 addition & 5 deletions src/support_code_library_builder/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ import TestRunHookDefinition from '../models/test_run_hook_definition'
import StepDefinition from '../models/step_definition'
import { formatLocation } from '../formatter/helpers'
import validateArguments from './validate_arguments'
import { deprecate } from 'util'
import arity from 'util-arity'

import {
Expand Down Expand Up @@ -120,10 +119,7 @@ export class SupportCodeLibraryBuilder {
() => this.beforeTestStepHookDefinitionConfigs
),
defineParameterType: this.defineParameterType.bind(this),
defineStep: deprecate(
this.defineStep('Unknown', () => this.stepDefinitionConfigs),
'`defineStep` is deprecated, use `Given`, `When` or `Then` instead; see https://github.com/cucumber/cucumber-js/issues/2043'
),
defineStep: this.defineStep('Unknown', () => this.stepDefinitionConfigs),
Given: this.defineStep('Given', () => this.stepDefinitionConfigs),
setDefaultTimeout: (milliseconds) => {
this.defaultTimeout = milliseconds
Expand Down
14 changes: 6 additions & 8 deletions src/wrapper.mjs
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
import cucumber from './index.js'

export const Cli = cucumber.Cli
export const parseGherkinMessageStream = cucumber.parseGherkinMessageStream
export const PickleFilter = cucumber.PickleFilter
export const Runtime = cucumber.Runtime
export const supportCodeLibraryBuilder = cucumber.supportCodeLibraryBuilder
export const Status = cucumber.Status
export const DataTable = cucumber.DataTable
Expand All @@ -28,10 +24,6 @@ export const Before = cucumber.Before
export const BeforeAll = cucumber.BeforeAll
export const BeforeStep = cucumber.BeforeStep
export const defineParameterType = cucumber.defineParameterType
/**
* @deprecated use `Given`, `When` or `Then` instead; see <https://github.com/cucumber/cucumber-js/issues/2043>
*/
export const defineStep = cucumber.defineStep
export const Given = cucumber.Given
export const setDefaultTimeout = cucumber.setDefaultTimeout
export const setDefinitionFunctionWrapper = cucumber.setDefinitionFunctionWrapper
Expand All @@ -43,3 +35,9 @@ export const parallelCanAssignHelpers = cucumber.parallelCanAssignHelpers

export const wrapPromiseWithTimeout = cucumber.wrapPromiseWithTimeout

// Deprecated
export const Cli = cucumber.Cli
export const defineStep = cucumber.defineStep
export const parseGherkinMessageStream = cucumber.parseGherkinMessageStream
export const PickleFilter = cucumber.PickleFilter
export const Runtime = cucumber.Runtime

0 comments on commit 6081893

Please sign in to comment.