diff --git a/CHANGELOG.md b/CHANGELOG.md index 76ad28808..07af2286a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO ([#1136](https://github.com/cucumber/cucumber-js/issues/1136) [#1721](https://github.com/cucumber/cucumber-js/pull/1721)) - Support for configuration to be objects instead of argv strings, and for configuration files in ESM and JSON formats ([#1952](https://github.com/cucumber/cucumber-js/pull/1952)) +- New API for running Cucumber programmatically (see [documentation](./docs/javascript_api.md)) ([#1955](https://github.com/cucumber/cucumber-js/pull/1955)) ### Fixed - Warn users who are on an unsupported node version ([#1922](https://github.com/cucumber/cucumber-js/pull/1922)) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f96eeac9a..f46d1d95e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,6 +41,10 @@ Type `npm run` or see the `package.json` scripts section for how to run each cat * feature tests - `npm run feature-test` * cucumber-js tests itself +## API Documentation + +The functionality exposed under the `@cucumber/cucumber/api` entry point is analysed and has documentation generated by [API Extractor](https://api-extractor.com/). If you make a change that affects the public API surface, you'll need to run `npm run docs:local` to run the analysis and regenerate the docs, and commit the changes. If you forget to do this locally, the CI build will fail and remind you. + ## Internals ### Project Structure @@ -48,7 +52,11 @@ Type `npm run` or see the `package.json` scripts section for how to run each cat ``` └── src │ - ├── cli # argv parsing, reading files + ├── api # main runCucumber function etc + │ + ├── cli # executing from argv + │ + ├── configuration # loading, merging, validating configuration │ ├── formatter # displaying the results │ diff --git a/api-extractor.json b/api-extractor.json new file mode 100644 index 000000000..41da06aaa --- /dev/null +++ b/api-extractor.json @@ -0,0 +1,25 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "mainEntryPointFilePath": "/lib/api/index.d.ts", + "compiler": { + }, + "apiReport": { + "enabled": true, + "reportFolder": "/reports/", + "reportTempFolder": "/tmp/api-extractor/" + }, + "docModel": { + "enabled": true, + "apiJsonFilePath": "/tmp/api-extractor/.api.json" + }, + "dtsRollup": { + "enabled": false + }, + "messages": { + "extractorMessageReporting": { + "ae-forgotten-export": { + "logLevel": "none" + } + } + } +} diff --git a/compatibility/cck_spec.ts b/compatibility/cck_spec.ts index 1bed551cd..104e7e24c 100644 --- a/compatibility/cck_spec.ts +++ b/compatibility/cck_spec.ts @@ -9,7 +9,7 @@ import { ignorableKeys } from '../features/support/formatter_output_helpers' import * as messages from '@cucumber/messages' import * as messageStreams from '@cucumber/message-streams' import util from 'util' -import { runCucumber, IRunnableConfiguration } from '../src/api' +import { runCucumber, IRunConfiguration } from '../src/api' import { Envelope } from '@cucumber/messages' const asyncPipeline = util.promisify(pipeline) @@ -29,7 +29,7 @@ describe('Cucumber Compatibility Kit', () => { const actualMessages: Envelope[] = [] const stdout = new PassThrough() const stderr = new PassThrough() - const runConfiguration: IRunnableConfiguration = { + const runConfiguration: IRunConfiguration = { sources: { defaultDialect: 'en', paths: [`${CCK_FEATURES_PATH}/${suiteName}/${suiteName}${extension}`], diff --git a/dependency-lint.yml b/dependency-lint.yml index a4a45798d..17fbca150 100644 --- a/dependency-lint.yml +++ b/dependency-lint.yml @@ -5,6 +5,8 @@ executedModules: npmScripts: dev: - build + - docs:ci + - docs:local - lint - publish - test diff --git a/docs/api/cucumber.iloadconfigurationoptions.file.md b/docs/api/cucumber.iloadconfigurationoptions.file.md new file mode 100644 index 000000000..47961cee0 --- /dev/null +++ b/docs/api/cucumber.iloadconfigurationoptions.file.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) > [file](./cucumber.iloadconfigurationoptions.file.md) + +## ILoadConfigurationOptions.file property + +Path to load configuration file from (defaults to `cucumber.(js|cjs|mjs|json)` if omitted). + +Signature: + +```typescript +file?: string; +``` diff --git a/docs/api/cucumber.iloadconfigurationoptions.md b/docs/api/cucumber.iloadconfigurationoptions.md new file mode 100644 index 000000000..14ee2e557 --- /dev/null +++ b/docs/api/cucumber.iloadconfigurationoptions.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) + +## ILoadConfigurationOptions interface + + +Signature: + +```typescript +export interface ILoadConfigurationOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [file?](./cucumber.iloadconfigurationoptions.file.md) | string | (Optional) Path to load configuration file from (defaults to cucumber.(js|cjs|mjs|json) if omitted). | +| [profiles?](./cucumber.iloadconfigurationoptions.profiles.md) | string\[\] | (Optional) Zero or more profile names from which to source configuration (if omitted or empty, the default profile will be used). | +| [provided?](./cucumber.iloadconfigurationoptions.provided.md) | Partial<IConfiguration> | (Optional) Ad-hoc configuration options to be applied over the top of whatever is loaded from the configuration file/profiles. | + diff --git a/docs/api/cucumber.iloadconfigurationoptions.profiles.md b/docs/api/cucumber.iloadconfigurationoptions.profiles.md new file mode 100644 index 000000000..35c129e88 --- /dev/null +++ b/docs/api/cucumber.iloadconfigurationoptions.profiles.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) > [profiles](./cucumber.iloadconfigurationoptions.profiles.md) + +## ILoadConfigurationOptions.profiles property + +Zero or more profile names from which to source configuration (if omitted or empty, the `default` profile will be used). + +Signature: + +```typescript +profiles?: string[]; +``` diff --git a/docs/api/cucumber.iloadconfigurationoptions.provided.md b/docs/api/cucumber.iloadconfigurationoptions.provided.md new file mode 100644 index 000000000..7078e6962 --- /dev/null +++ b/docs/api/cucumber.iloadconfigurationoptions.provided.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) > [provided](./cucumber.iloadconfigurationoptions.provided.md) + +## ILoadConfigurationOptions.provided property + +Ad-hoc configuration options to be applied over the top of whatever is loaded from the configuration file/profiles. + +Signature: + +```typescript +provided?: Partial; +``` diff --git a/docs/api/cucumber.iloadsupportoptions.md b/docs/api/cucumber.iloadsupportoptions.md new file mode 100644 index 000000000..1722a0953 --- /dev/null +++ b/docs/api/cucumber.iloadsupportoptions.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) + +## ILoadSupportOptions interface + + +Signature: + +```typescript +export interface ILoadSupportOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [sources](./cucumber.iloadsupportoptions.sources.md) | [ISourcesCoordinates](./cucumber.isourcescoordinates.md) | | +| [support](./cucumber.iloadsupportoptions.support.md) | [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) | | + diff --git a/docs/api/cucumber.iloadsupportoptions.sources.md b/docs/api/cucumber.iloadsupportoptions.sources.md new file mode 100644 index 000000000..7d9ad0b5a --- /dev/null +++ b/docs/api/cucumber.iloadsupportoptions.sources.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) > [sources](./cucumber.iloadsupportoptions.sources.md) + +## ILoadSupportOptions.sources property + +Signature: + +```typescript +sources: ISourcesCoordinates; +``` diff --git a/docs/api/cucumber.iloadsupportoptions.support.md b/docs/api/cucumber.iloadsupportoptions.support.md new file mode 100644 index 000000000..222dd6c9a --- /dev/null +++ b/docs/api/cucumber.iloadsupportoptions.support.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) > [support](./cucumber.iloadsupportoptions.support.md) + +## ILoadSupportOptions.support property + +Signature: + +```typescript +support: ISupportCodeCoordinates; +``` diff --git a/docs/api/cucumber.iresolvedconfiguration.md b/docs/api/cucumber.iresolvedconfiguration.md new file mode 100644 index 000000000..d99bb7c30 --- /dev/null +++ b/docs/api/cucumber.iresolvedconfiguration.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md) + +## IResolvedConfiguration interface + + +Signature: + +```typescript +export interface IResolvedConfiguration +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [runConfiguration](./cucumber.iresolvedconfiguration.runconfiguration.md) | [IRunConfiguration](./cucumber.irunconfiguration.md) | The format that can be passed into runCucumber. | +| [useConfiguration](./cucumber.iresolvedconfiguration.useconfiguration.md) | IConfiguration | The final flat configuration object resolved from the configuration file/profiles plus any extra provided. | + diff --git a/docs/api/cucumber.iresolvedconfiguration.runconfiguration.md b/docs/api/cucumber.iresolvedconfiguration.runconfiguration.md new file mode 100644 index 000000000..2e9264b0f --- /dev/null +++ b/docs/api/cucumber.iresolvedconfiguration.runconfiguration.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md) > [runConfiguration](./cucumber.iresolvedconfiguration.runconfiguration.md) + +## IResolvedConfiguration.runConfiguration property + +The format that can be passed into `runCucumber`. + +Signature: + +```typescript +runConfiguration: IRunConfiguration; +``` diff --git a/docs/api/cucumber.iresolvedconfiguration.useconfiguration.md b/docs/api/cucumber.iresolvedconfiguration.useconfiguration.md new file mode 100644 index 000000000..ae5aef140 --- /dev/null +++ b/docs/api/cucumber.iresolvedconfiguration.useconfiguration.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md) > [useConfiguration](./cucumber.iresolvedconfiguration.useconfiguration.md) + +## IResolvedConfiguration.useConfiguration property + +The final flat configuration object resolved from the configuration file/profiles plus any extra provided. + +Signature: + +```typescript +useConfiguration: IConfiguration; +``` diff --git a/docs/api/cucumber.irunconfiguration.formats.md b/docs/api/cucumber.irunconfiguration.formats.md new file mode 100644 index 000000000..6a4578565 --- /dev/null +++ b/docs/api/cucumber.irunconfiguration.formats.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunConfiguration](./cucumber.irunconfiguration.md) > [formats](./cucumber.irunconfiguration.formats.md) + +## IRunConfiguration.formats property + +Signature: + +```typescript +formats: IRunOptionsFormats; +``` diff --git a/docs/api/cucumber.irunconfiguration.md b/docs/api/cucumber.irunconfiguration.md new file mode 100644 index 000000000..2e42f2ec6 --- /dev/null +++ b/docs/api/cucumber.irunconfiguration.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunConfiguration](./cucumber.irunconfiguration.md) + +## IRunConfiguration interface + + +Signature: + +```typescript +export interface IRunConfiguration +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [formats](./cucumber.irunconfiguration.formats.md) | [IRunOptionsFormats](./cucumber.irunoptionsformats.md) | | +| [runtime](./cucumber.irunconfiguration.runtime.md) | [IRunOptionsRuntime](./cucumber.irunoptionsruntime.md) | | +| [sources](./cucumber.irunconfiguration.sources.md) | [ISourcesCoordinates](./cucumber.isourcescoordinates.md) | | +| [support](./cucumber.irunconfiguration.support.md) | [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) | | + diff --git a/docs/api/cucumber.irunconfiguration.runtime.md b/docs/api/cucumber.irunconfiguration.runtime.md new file mode 100644 index 000000000..7c651576d --- /dev/null +++ b/docs/api/cucumber.irunconfiguration.runtime.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunConfiguration](./cucumber.irunconfiguration.md) > [runtime](./cucumber.irunconfiguration.runtime.md) + +## IRunConfiguration.runtime property + +Signature: + +```typescript +runtime: IRunOptionsRuntime; +``` diff --git a/docs/api/cucumber.irunconfiguration.sources.md b/docs/api/cucumber.irunconfiguration.sources.md new file mode 100644 index 000000000..e0a68beda --- /dev/null +++ b/docs/api/cucumber.irunconfiguration.sources.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunConfiguration](./cucumber.irunconfiguration.md) > [sources](./cucumber.irunconfiguration.sources.md) + +## IRunConfiguration.sources property + +Signature: + +```typescript +sources: ISourcesCoordinates; +``` diff --git a/docs/api/cucumber.irunconfiguration.support.md b/docs/api/cucumber.irunconfiguration.support.md new file mode 100644 index 000000000..07036bc2c --- /dev/null +++ b/docs/api/cucumber.irunconfiguration.support.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunConfiguration](./cucumber.irunconfiguration.md) > [support](./cucumber.irunconfiguration.support.md) + +## IRunConfiguration.support property + +Signature: + +```typescript +support: ISupportCodeCoordinates; +``` diff --git a/docs/api/cucumber.irunenvironment.cwd.md b/docs/api/cucumber.irunenvironment.cwd.md new file mode 100644 index 000000000..efe7d2aa3 --- /dev/null +++ b/docs/api/cucumber.irunenvironment.cwd.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunEnvironment](./cucumber.irunenvironment.md) > [cwd](./cucumber.irunenvironment.cwd.md) + +## IRunEnvironment.cwd property + +Working directory for the project (defaults to `process.cwd()` if omitted). + +Signature: + +```typescript +cwd?: string; +``` diff --git a/docs/api/cucumber.irunenvironment.env.md b/docs/api/cucumber.irunenvironment.env.md new file mode 100644 index 000000000..cac334c97 --- /dev/null +++ b/docs/api/cucumber.irunenvironment.env.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunEnvironment](./cucumber.irunenvironment.md) > [env](./cucumber.irunenvironment.env.md) + +## IRunEnvironment.env property + +Environment variables (defaults to `process.env` if omitted). + +Signature: + +```typescript +env?: NodeJS.ProcessEnv; +``` diff --git a/docs/api/cucumber.irunenvironment.md b/docs/api/cucumber.irunenvironment.md new file mode 100644 index 000000000..a563ff692 --- /dev/null +++ b/docs/api/cucumber.irunenvironment.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunEnvironment](./cucumber.irunenvironment.md) + +## IRunEnvironment interface + +Contextual data about the project environment. + +Signature: + +```typescript +export interface IRunEnvironment +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [cwd?](./cucumber.irunenvironment.cwd.md) | string | (Optional) Working directory for the project (defaults to process.cwd() if omitted). | +| [env?](./cucumber.irunenvironment.env.md) | NodeJS.ProcessEnv | (Optional) Environment variables (defaults to process.env if omitted). | +| [stderr?](./cucumber.irunenvironment.stderr.md) | IFormatterStream | (Optional) Writable stream where the test run's warning/error output is written (defaults to process.stderr if omitted). | +| [stdout?](./cucumber.irunenvironment.stdout.md) | IFormatterStream | (Optional) Writable stream where the test run's main output is written (defaults to process.stdout if omitted). | + diff --git a/docs/api/cucumber.irunenvironment.stderr.md b/docs/api/cucumber.irunenvironment.stderr.md new file mode 100644 index 000000000..4a0162c95 --- /dev/null +++ b/docs/api/cucumber.irunenvironment.stderr.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunEnvironment](./cucumber.irunenvironment.md) > [stderr](./cucumber.irunenvironment.stderr.md) + +## IRunEnvironment.stderr property + +Writable stream where the test run's warning/error output is written (defaults to `process.stderr` if omitted). + +Signature: + +```typescript +stderr?: IFormatterStream; +``` diff --git a/docs/api/cucumber.irunenvironment.stdout.md b/docs/api/cucumber.irunenvironment.stdout.md new file mode 100644 index 000000000..f72e61807 --- /dev/null +++ b/docs/api/cucumber.irunenvironment.stdout.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunEnvironment](./cucumber.irunenvironment.md) > [stdout](./cucumber.irunenvironment.stdout.md) + +## IRunEnvironment.stdout property + +Writable stream where the test run's main output is written (defaults to `process.stdout` if omitted). + +Signature: + +```typescript +stdout?: IFormatterStream; +``` diff --git a/docs/api/cucumber.irunoptions.formats.md b/docs/api/cucumber.irunoptions.formats.md new file mode 100644 index 000000000..c31e76fb5 --- /dev/null +++ b/docs/api/cucumber.irunoptions.formats.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptions](./cucumber.irunoptions.md) > [formats](./cucumber.irunoptions.formats.md) + +## IRunOptions.formats property + +Signature: + +```typescript +formats: IRunOptionsFormats; +``` diff --git a/docs/api/cucumber.irunoptions.md b/docs/api/cucumber.irunoptions.md new file mode 100644 index 000000000..836b6d3e2 --- /dev/null +++ b/docs/api/cucumber.irunoptions.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptions](./cucumber.irunoptions.md) + +## IRunOptions interface + + +Signature: + +```typescript +export interface IRunOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [formats](./cucumber.irunoptions.formats.md) | [IRunOptionsFormats](./cucumber.irunoptionsformats.md) | | +| [runtime](./cucumber.irunoptions.runtime.md) | [IRunOptionsRuntime](./cucumber.irunoptionsruntime.md) | | +| [sources](./cucumber.irunoptions.sources.md) | [ISourcesCoordinates](./cucumber.isourcescoordinates.md) | | +| [support](./cucumber.irunoptions.support.md) | [ISupportCodeCoordinatesOrLibrary](./cucumber.isupportcodecoordinatesorlibrary.md) | | + diff --git a/docs/api/cucumber.irunoptions.runtime.md b/docs/api/cucumber.irunoptions.runtime.md new file mode 100644 index 000000000..ec46ae891 --- /dev/null +++ b/docs/api/cucumber.irunoptions.runtime.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptions](./cucumber.irunoptions.md) > [runtime](./cucumber.irunoptions.runtime.md) + +## IRunOptions.runtime property + +Signature: + +```typescript +runtime: IRunOptionsRuntime; +``` diff --git a/docs/api/cucumber.irunoptions.sources.md b/docs/api/cucumber.irunoptions.sources.md new file mode 100644 index 000000000..2b5fba724 --- /dev/null +++ b/docs/api/cucumber.irunoptions.sources.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptions](./cucumber.irunoptions.md) > [sources](./cucumber.irunoptions.sources.md) + +## IRunOptions.sources property + +Signature: + +```typescript +sources: ISourcesCoordinates; +``` diff --git a/docs/api/cucumber.irunoptions.support.md b/docs/api/cucumber.irunoptions.support.md new file mode 100644 index 000000000..d89dc3652 --- /dev/null +++ b/docs/api/cucumber.irunoptions.support.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptions](./cucumber.irunoptions.md) > [support](./cucumber.irunoptions.support.md) + +## IRunOptions.support property + +Signature: + +```typescript +support: ISupportCodeCoordinatesOrLibrary; +``` diff --git a/docs/api/cucumber.irunoptionsformats.files.md b/docs/api/cucumber.irunoptionsformats.files.md new file mode 100644 index 000000000..c9b701526 --- /dev/null +++ b/docs/api/cucumber.irunoptionsformats.files.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptionsFormats](./cucumber.irunoptionsformats.md) > [files](./cucumber.irunoptionsformats.files.md) + +## IRunOptionsFormats.files property + +Signature: + +```typescript +files: Record; +``` diff --git a/docs/api/cucumber.irunoptionsformats.md b/docs/api/cucumber.irunoptionsformats.md new file mode 100644 index 000000000..f2a9c337b --- /dev/null +++ b/docs/api/cucumber.irunoptionsformats.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptionsFormats](./cucumber.irunoptionsformats.md) + +## IRunOptionsFormats interface + + +Signature: + +```typescript +export interface IRunOptionsFormats +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [files](./cucumber.irunoptionsformats.files.md) | Record<string, string> | | +| [options](./cucumber.irunoptionsformats.options.md) | FormatOptions | | +| [publish](./cucumber.irunoptionsformats.publish.md) | { url?: string; token?: string; } \| false | | +| [stdout](./cucumber.irunoptionsformats.stdout.md) | string | | + diff --git a/docs/api/cucumber.irunoptionsformats.options.md b/docs/api/cucumber.irunoptionsformats.options.md new file mode 100644 index 000000000..696353b4d --- /dev/null +++ b/docs/api/cucumber.irunoptionsformats.options.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptionsFormats](./cucumber.irunoptionsformats.md) > [options](./cucumber.irunoptionsformats.options.md) + +## IRunOptionsFormats.options property + +Signature: + +```typescript +options: FormatOptions; +``` diff --git a/docs/api/cucumber.irunoptionsformats.publish.md b/docs/api/cucumber.irunoptionsformats.publish.md new file mode 100644 index 000000000..d416ed77d --- /dev/null +++ b/docs/api/cucumber.irunoptionsformats.publish.md @@ -0,0 +1,14 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptionsFormats](./cucumber.irunoptionsformats.md) > [publish](./cucumber.irunoptionsformats.publish.md) + +## IRunOptionsFormats.publish property + +Signature: + +```typescript +publish: { + url?: string; + token?: string; + } | false; +``` diff --git a/docs/api/cucumber.irunoptionsformats.stdout.md b/docs/api/cucumber.irunoptionsformats.stdout.md new file mode 100644 index 000000000..175c5708e --- /dev/null +++ b/docs/api/cucumber.irunoptionsformats.stdout.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptionsFormats](./cucumber.irunoptionsformats.md) > [stdout](./cucumber.irunoptionsformats.stdout.md) + +## IRunOptionsFormats.stdout property + +Signature: + +```typescript +stdout: string; +``` diff --git a/docs/api/cucumber.irunoptionsruntime.md b/docs/api/cucumber.irunoptionsruntime.md new file mode 100644 index 000000000..7c87ea4df --- /dev/null +++ b/docs/api/cucumber.irunoptionsruntime.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptionsRuntime](./cucumber.irunoptionsruntime.md) + +## IRunOptionsRuntime interface + + +Signature: + +```typescript +export interface IRunOptionsRuntime extends IRuntimeOptions +``` +Extends: IRuntimeOptions + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [parallel](./cucumber.irunoptionsruntime.parallel.md) | number | | + diff --git a/docs/api/cucumber.irunoptionsruntime.parallel.md b/docs/api/cucumber.irunoptionsruntime.parallel.md new file mode 100644 index 000000000..6deaa4ab7 --- /dev/null +++ b/docs/api/cucumber.irunoptionsruntime.parallel.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunOptionsRuntime](./cucumber.irunoptionsruntime.md) > [parallel](./cucumber.irunoptionsruntime.parallel.md) + +## IRunOptionsRuntime.parallel property + +Signature: + +```typescript +parallel: number; +``` diff --git a/docs/api/cucumber.irunresult.md b/docs/api/cucumber.irunresult.md new file mode 100644 index 000000000..af36dc92b --- /dev/null +++ b/docs/api/cucumber.irunresult.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunResult](./cucumber.irunresult.md) + +## IRunResult interface + +Result of a Cucumber test run. + +Signature: + +```typescript +export interface IRunResult +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [success](./cucumber.irunresult.success.md) | boolean | Whether the test run was overall successful i.e. no failed scenarios. The exact meaning can vary based on the strict configuration option. | +| [support](./cucumber.irunresult.support.md) | ISupportCodeLibrary | The support code library that was used in the test run; can be reused in subsequent runCucumber calls. | + diff --git a/docs/api/cucumber.irunresult.success.md b/docs/api/cucumber.irunresult.success.md new file mode 100644 index 000000000..cd22c6c17 --- /dev/null +++ b/docs/api/cucumber.irunresult.success.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunResult](./cucumber.irunresult.md) > [success](./cucumber.irunresult.success.md) + +## IRunResult.success property + +Whether the test run was overall successful i.e. no failed scenarios. The exact meaning can vary based on the `strict` configuration option. + +Signature: + +```typescript +success: boolean; +``` diff --git a/docs/api/cucumber.irunresult.support.md b/docs/api/cucumber.irunresult.support.md new file mode 100644 index 000000000..df5bb64e1 --- /dev/null +++ b/docs/api/cucumber.irunresult.support.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [IRunResult](./cucumber.irunresult.md) > [support](./cucumber.irunresult.support.md) + +## IRunResult.support property + +The support code library that was used in the test run; can be reused in subsequent `runCucumber` calls. + +Signature: + +```typescript +support: ISupportCodeLibrary; +``` diff --git a/docs/api/cucumber.isourcescoordinates.defaultdialect.md b/docs/api/cucumber.isourcescoordinates.defaultdialect.md new file mode 100644 index 000000000..8e0e43211 --- /dev/null +++ b/docs/api/cucumber.isourcescoordinates.defaultdialect.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISourcesCoordinates](./cucumber.isourcescoordinates.md) > [defaultDialect](./cucumber.isourcescoordinates.defaultdialect.md) + +## ISourcesCoordinates.defaultDialect property + +Signature: + +```typescript +defaultDialect: string; +``` diff --git a/docs/api/cucumber.isourcescoordinates.md b/docs/api/cucumber.isourcescoordinates.md new file mode 100644 index 000000000..d7bfe8005 --- /dev/null +++ b/docs/api/cucumber.isourcescoordinates.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISourcesCoordinates](./cucumber.isourcescoordinates.md) + +## ISourcesCoordinates interface + + +Signature: + +```typescript +export interface ISourcesCoordinates +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [defaultDialect](./cucumber.isourcescoordinates.defaultdialect.md) | string | | +| [names](./cucumber.isourcescoordinates.names.md) | string\[\] | | +| [order](./cucumber.isourcescoordinates.order.md) | PickleOrder | | +| [paths](./cucumber.isourcescoordinates.paths.md) | string\[\] | | +| [tagExpression](./cucumber.isourcescoordinates.tagexpression.md) | string | | + diff --git a/docs/api/cucumber.isourcescoordinates.names.md b/docs/api/cucumber.isourcescoordinates.names.md new file mode 100644 index 000000000..756541844 --- /dev/null +++ b/docs/api/cucumber.isourcescoordinates.names.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISourcesCoordinates](./cucumber.isourcescoordinates.md) > [names](./cucumber.isourcescoordinates.names.md) + +## ISourcesCoordinates.names property + +Signature: + +```typescript +names: string[]; +``` diff --git a/docs/api/cucumber.isourcescoordinates.order.md b/docs/api/cucumber.isourcescoordinates.order.md new file mode 100644 index 000000000..2c669710a --- /dev/null +++ b/docs/api/cucumber.isourcescoordinates.order.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISourcesCoordinates](./cucumber.isourcescoordinates.md) > [order](./cucumber.isourcescoordinates.order.md) + +## ISourcesCoordinates.order property + +Signature: + +```typescript +order: PickleOrder; +``` diff --git a/docs/api/cucumber.isourcescoordinates.paths.md b/docs/api/cucumber.isourcescoordinates.paths.md new file mode 100644 index 000000000..0a2143a5a --- /dev/null +++ b/docs/api/cucumber.isourcescoordinates.paths.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISourcesCoordinates](./cucumber.isourcescoordinates.md) > [paths](./cucumber.isourcescoordinates.paths.md) + +## ISourcesCoordinates.paths property + +Signature: + +```typescript +paths: string[]; +``` diff --git a/docs/api/cucumber.isourcescoordinates.tagexpression.md b/docs/api/cucumber.isourcescoordinates.tagexpression.md new file mode 100644 index 000000000..311775818 --- /dev/null +++ b/docs/api/cucumber.isourcescoordinates.tagexpression.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISourcesCoordinates](./cucumber.isourcescoordinates.md) > [tagExpression](./cucumber.isourcescoordinates.tagexpression.md) + +## ISourcesCoordinates.tagExpression property + +Signature: + +```typescript +tagExpression: string; +``` diff --git a/docs/api/cucumber.isupportcodecoordinates.importpaths.md b/docs/api/cucumber.isupportcodecoordinates.importpaths.md new file mode 100644 index 000000000..34e8034de --- /dev/null +++ b/docs/api/cucumber.isupportcodecoordinates.importpaths.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) > [importPaths](./cucumber.isupportcodecoordinates.importpaths.md) + +## ISupportCodeCoordinates.importPaths property + +Signature: + +```typescript +importPaths: string[]; +``` diff --git a/docs/api/cucumber.isupportcodecoordinates.md b/docs/api/cucumber.isupportcodecoordinates.md new file mode 100644 index 000000000..87ab944c5 --- /dev/null +++ b/docs/api/cucumber.isupportcodecoordinates.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) + +## ISupportCodeCoordinates interface + + +Signature: + +```typescript +export interface ISupportCodeCoordinates +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [importPaths](./cucumber.isupportcodecoordinates.importpaths.md) | string\[\] | | +| [requireModules](./cucumber.isupportcodecoordinates.requiremodules.md) | string\[\] | | +| [requirePaths](./cucumber.isupportcodecoordinates.requirepaths.md) | string\[\] | | + diff --git a/docs/api/cucumber.isupportcodecoordinates.requiremodules.md b/docs/api/cucumber.isupportcodecoordinates.requiremodules.md new file mode 100644 index 000000000..f4bac3175 --- /dev/null +++ b/docs/api/cucumber.isupportcodecoordinates.requiremodules.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) > [requireModules](./cucumber.isupportcodecoordinates.requiremodules.md) + +## ISupportCodeCoordinates.requireModules property + +Signature: + +```typescript +requireModules: string[]; +``` diff --git a/docs/api/cucumber.isupportcodecoordinates.requirepaths.md b/docs/api/cucumber.isupportcodecoordinates.requirepaths.md new file mode 100644 index 000000000..4ac57b619 --- /dev/null +++ b/docs/api/cucumber.isupportcodecoordinates.requirepaths.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) > [requirePaths](./cucumber.isupportcodecoordinates.requirepaths.md) + +## ISupportCodeCoordinates.requirePaths property + +Signature: + +```typescript +requirePaths: string[]; +``` diff --git a/docs/api/cucumber.isupportcodecoordinatesorlibrary.md b/docs/api/cucumber.isupportcodecoordinatesorlibrary.md new file mode 100644 index 000000000..ba6d1c040 --- /dev/null +++ b/docs/api/cucumber.isupportcodecoordinatesorlibrary.md @@ -0,0 +1,14 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [ISupportCodeCoordinatesOrLibrary](./cucumber.isupportcodecoordinatesorlibrary.md) + +## ISupportCodeCoordinatesOrLibrary type + + +Signature: + +```typescript +export declare type ISupportCodeCoordinatesOrLibrary = ISupportCodeCoordinates | ISupportCodeLibrary; +``` +References: [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) + diff --git a/docs/api/cucumber.loadconfiguration.md b/docs/api/cucumber.loadconfiguration.md new file mode 100644 index 000000000..eaaeec41c --- /dev/null +++ b/docs/api/cucumber.loadconfiguration.md @@ -0,0 +1,25 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [loadConfiguration](./cucumber.loadconfiguration.md) + +## loadConfiguration() function + +Load user-authored configuration to be used in a test run. + +Signature: + +```typescript +export declare function loadConfiguration(options?: ILoadConfigurationOptions, environment?: IRunEnvironment): Promise; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) | Coordinates required to find configuration. | +| environment | [IRunEnvironment](./cucumber.irunenvironment.md) | Project environment. | + +Returns: + +Promise<[IResolvedConfiguration](./cucumber.iresolvedconfiguration.md)> + diff --git a/docs/api/cucumber.loadsupport.md b/docs/api/cucumber.loadsupport.md new file mode 100644 index 000000000..95dd95025 --- /dev/null +++ b/docs/api/cucumber.loadsupport.md @@ -0,0 +1,25 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [loadSupport](./cucumber.loadsupport.md) + +## loadSupport() function + +Load support code for use in test runs. + +Signature: + +```typescript +export declare function loadSupport(options: ILoadSupportOptions, environment?: IRunEnvironment): Promise; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) | Subset of IRunnableConfiguration required to find the support code. | +| environment | [IRunEnvironment](./cucumber.irunenvironment.md) | Project environment. | + +Returns: + +Promise<ISupportCodeLibrary> + diff --git a/docs/api/cucumber.md b/docs/api/cucumber.md new file mode 100644 index 000000000..915718081 --- /dev/null +++ b/docs/api/cucumber.md @@ -0,0 +1,42 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) + +## cucumber package + +Cucumber for JavaScript + +## Remarks + +These docs cover the API used for running Cucumber programmatically. The entry point is `@cucumber/cucumber/api`. + +## Functions + +| Function | Description | +| --- | --- | +| [loadConfiguration(options, environment)](./cucumber.loadconfiguration.md) | Load user-authored configuration to be used in a test run. | +| [loadSupport(options, environment)](./cucumber.loadsupport.md) | Load support code for use in test runs. | +| [runCucumber(configuration, environment, onMessage)](./cucumber.runcucumber.md) | Execute a Cucumber test run. | + +## Interfaces + +| Interface | Description | +| --- | --- | +| [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) | | +| [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) | | +| [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md) | | +| [IRunConfiguration](./cucumber.irunconfiguration.md) | | +| [IRunEnvironment](./cucumber.irunenvironment.md) | Contextual data about the project environment. | +| [IRunOptions](./cucumber.irunoptions.md) | | +| [IRunOptionsFormats](./cucumber.irunoptionsformats.md) | | +| [IRunOptionsRuntime](./cucumber.irunoptionsruntime.md) | | +| [IRunResult](./cucumber.irunresult.md) | Result of a Cucumber test run. | +| [ISourcesCoordinates](./cucumber.isourcescoordinates.md) | | +| [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) | | + +## Type Aliases + +| Type Alias | Description | +| --- | --- | +| [ISupportCodeCoordinatesOrLibrary](./cucumber.isupportcodecoordinatesorlibrary.md) | | + diff --git a/docs/api/cucumber.runcucumber.md b/docs/api/cucumber.runcucumber.md new file mode 100644 index 000000000..dc444056e --- /dev/null +++ b/docs/api/cucumber.runcucumber.md @@ -0,0 +1,26 @@ + + +[Home](./index.md) > [@cucumber/cucumber](./cucumber.md) > [runCucumber](./cucumber.runcucumber.md) + +## runCucumber() function + +Execute a Cucumber test run. + +Signature: + +```typescript +export declare function runCucumber(configuration: IRunOptions, environment?: IRunEnvironment, onMessage?: (message: Envelope) => void): Promise; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| configuration | [IRunOptions](./cucumber.irunoptions.md) | Configuration loaded from loadConfiguration. | +| environment | [IRunEnvironment](./cucumber.irunenvironment.md) | Project environment. | +| onMessage | (message: Envelope) => void | Callback fired each time Cucumber emits a message. | + +Returns: + +Promise<[IRunResult](./cucumber.irunresult.md)> + diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 000000000..eddac6dd2 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,12 @@ + + +[Home](./index.md) + +## API Reference + +## Packages + +| Package | Description | +| --- | --- | +| [@cucumber/cucumber](./cucumber.md) | Cucumber for JavaScript | + diff --git a/docs/javascript_api.md b/docs/javascript_api.md new file mode 100644 index 000000000..a533096d2 --- /dev/null +++ b/docs/javascript_api.md @@ -0,0 +1,37 @@ +# JavaScript API + +You can run Cucumber programmatically via its JavaScript API. This isn't something most users would need to do, but if you have a niche use case or need to work Cucumber into a bigger framework, it might be what you need. The API allows you to load configuration, sources and support code and execute test runs with async functions and within the current process. + +The API is available on its own entry point `@cucumber/cucumber/api`. + +There are some examples below, and [reference documentation](./api/index.md) for everything available. + +## Simple example + +```javascript +import { loadConfiguration, runCucumber } from '@cucumber/cucumber/api' + +export async function runTests() { + const { runConfiguration } = await loadConfiguration() + const { success } = await runCucumber(runConfiguration) + return success +} +``` + +## Complex example + +```javascript +import { loadConfiguration, loadSupport, runCucumber } from '@cucumber/cucumber/api' + +export async function runTests(directory, configFile, failFast) { + // things we need to specify about the environment + const environment = { cwd: directory } + // load configuration from a particular file, and override a specific option + const { runConfiguration } = await loadConfiguration({ file: configFile, provided: { failFast } }, environment) + // load the support code upfront + const support = await loadSupport(runnable, environment) + // run cucumber, using the support code we loaded already + const { success } = await runCucumber({ ...runConfiguration, support }, environment) + return success +} +``` diff --git a/package-lock.json b/package-lock.json index 173411630..be449c1b0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11,7 +11,7 @@ "dependencies": { "@cspotcode/source-map-support": "^0.7.0", "@cucumber/ci-environment": "9.0.0", - "@cucumber/cucumber-expressions": "15.0.1", + "@cucumber/cucumber-expressions": "15.0.2", "@cucumber/gherkin": "22.0.0", "@cucumber/gherkin-streams": "4.0.0", "@cucumber/html-formatter": "18.0.0", @@ -50,6 +50,8 @@ "@cucumber/compatibility-kit": "9.1.2", "@cucumber/message-streams": "3.0.0", "@cucumber/query": "11.0.0", + "@microsoft/api-documenter": "^7.15.3", + "@microsoft/api-extractor": "^7.19.4", "@sinonjs/fake-timers": "9.1.0", "@types/chai": "4.3.0", "@types/dirty-chai": "2.0.2", @@ -441,9 +443,9 @@ } }, "node_modules/@babel/runtime": { - "version": "7.17.2", - "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.17.2.tgz", - "integrity": "sha512-hzeyJyMA1YGdJTuWU0e/j4wKXrU4OMFvY2MSlaI9B7VQb0r5cxTE3EAIS2Q7Tn2RIcDkRvTA/v2JsAEhxe99uw==", + "version": "7.17.7", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.17.7.tgz", + "integrity": "sha512-L6rvG9GDxaLgFjg41K+5Yv9OMrU98sWe+Ykmc6FDJW/+vYZMhdOMKkISgzptMaERHvS2Y2lw9MDRm2gHhlQQoA==", "dependencies": { "regenerator-runtime": "^0.13.4" }, @@ -539,9 +541,9 @@ "dev": true }, "node_modules/@cucumber/cucumber-expressions": { - "version": "15.0.1", - "resolved": "https://registry.npmjs.org/@cucumber/cucumber-expressions/-/cucumber-expressions-15.0.1.tgz", - "integrity": "sha512-TFUjz20+4OpHXDGXN7fv+JDSYkTvdakz1R/2OEV8gqYAkPUhjx+jeiyDF6C0rPzx9MoD7B3DoPfcfA2nS3Bh4w==", + "version": "15.0.2", + "resolved": "https://registry.npmjs.org/@cucumber/cucumber-expressions/-/cucumber-expressions-15.0.2.tgz", + "integrity": "sha512-ppN9JL1C5lw3InvM7WnoKZV9La5PW5Vr8c/8J0ZGzdlC8Y+PB7kskGzx7/tzl9kGjq7USQ7MZfwFz5el2sB/GA==", "dependencies": { "regexp-match-indices": "1.0.2" } @@ -830,6 +832,166 @@ "node": ">=8" } }, + "node_modules/@microsoft/api-documenter": { + "version": "7.15.3", + "resolved": "https://registry.npmjs.org/@microsoft/api-documenter/-/api-documenter-7.15.3.tgz", + "integrity": "sha512-tehv1f/aKwGBQp0sheQofz5NQfa61mvTdAe4IHQnVavsyyK71r+P+CVXWewznPYkqFzzVXaTdrCuNGPU5Yd3mg==", + "dev": true, + "dependencies": { + "@microsoft/api-extractor-model": "7.15.3", + "@microsoft/tsdoc": "0.13.2", + "@rushstack/node-core-library": "3.45.0", + "@rushstack/ts-command-line": "4.10.6", + "colors": "~1.2.1", + "js-yaml": "~3.13.1", + "resolve": "~1.17.0" + }, + "bin": { + "api-documenter": "bin/api-documenter" + } + }, + "node_modules/@microsoft/api-documenter/node_modules/colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true, + "engines": { + "node": ">=0.1.90" + } + }, + "node_modules/@microsoft/api-documenter/node_modules/js-yaml": { + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "dev": true, + "dependencies": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/@microsoft/api-documenter/node_modules/resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "dependencies": { + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/@microsoft/api-extractor": { + "version": "7.19.4", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.19.4.tgz", + "integrity": "sha512-iehC6YA3DGJvxTUaK7HUtQmP6hAQU07+Q/OR8TG4dVR6KpqCi9UPEVk8AgCvQkiK+6FbVEFQTx0qLuYk4EeuHg==", + "dev": true, + "dependencies": { + "@microsoft/api-extractor-model": "7.15.3", + "@microsoft/tsdoc": "0.13.2", + "@microsoft/tsdoc-config": "~0.15.2", + "@rushstack/node-core-library": "3.45.0", + "@rushstack/rig-package": "0.3.7", + "@rushstack/ts-command-line": "4.10.6", + "colors": "~1.2.1", + "lodash": "~4.17.15", + "resolve": "~1.17.0", + "semver": "~7.3.0", + "source-map": "~0.6.1", + "typescript": "~4.5.2" + }, + "bin": { + "api-extractor": "bin/api-extractor" + } + }, + "node_modules/@microsoft/api-extractor-model": { + "version": "7.15.3", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.15.3.tgz", + "integrity": "sha512-NkSjolmSI7NGvbdz0Y7kjQfdpD+j9E5CwXTxEyjDqxd10MI7GXV8DnAsQ57GFJcgHKgTjf2aUnYfMJ9w3aMicw==", + "dev": true, + "dependencies": { + "@microsoft/tsdoc": "0.13.2", + "@microsoft/tsdoc-config": "~0.15.2", + "@rushstack/node-core-library": "3.45.0" + } + }, + "node_modules/@microsoft/api-extractor/node_modules/colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true, + "engines": { + "node": ">=0.1.90" + } + }, + "node_modules/@microsoft/api-extractor/node_modules/resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "dependencies": { + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/@microsoft/api-extractor/node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/@microsoft/api-extractor/node_modules/typescript": { + "version": "4.5.5", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.5.5.tgz", + "integrity": "sha512-TCTIul70LyWe6IJWT8QSYeA54WQe8EjQFU4wY52Fasj5UKx88LNYKCgBEHcOMOrFF1rKGbD8v/xcNWVUq9SymA==", + "dev": true, + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=4.2.0" + } + }, + "node_modules/@microsoft/tsdoc": { + "version": "0.13.2", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc/-/tsdoc-0.13.2.tgz", + "integrity": "sha512-WrHvO8PDL8wd8T2+zBGKrMwVL5IyzR3ryWUsl0PXgEV0QHup4mTLi0QcATefGI6Gx9Anu7vthPyyyLpY0EpiQg==", + "dev": true + }, + "node_modules/@microsoft/tsdoc-config": { + "version": "0.15.2", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc-config/-/tsdoc-config-0.15.2.tgz", + "integrity": "sha512-mK19b2wJHSdNf8znXSMYVShAHktVr/ib0Ck2FA3lsVBSEhSI/TfXT7DJQkAYgcztTuwazGcg58ZjYdk0hTCVrA==", + "dev": true, + "dependencies": { + "@microsoft/tsdoc": "0.13.2", + "ajv": "~6.12.6", + "jju": "~1.4.0", + "resolve": "~1.19.0" + } + }, + "node_modules/@microsoft/tsdoc-config/node_modules/resolve": { + "version": "1.19.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.19.0.tgz", + "integrity": "sha512-rArEXAgsBG4UgRGcynxWIWKFvh/XZCcS8UJdHhwy91zwAvCZIbcs+vAbflgBnNjYMs/i/i+/Ux6IZhML1yPvxg==", + "dev": true, + "dependencies": { + "is-core-module": "^2.1.0", + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, "node_modules/@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", @@ -865,6 +1027,125 @@ "node": ">= 8" } }, + "node_modules/@rushstack/node-core-library": { + "version": "3.45.0", + "resolved": "https://registry.npmjs.org/@rushstack/node-core-library/-/node-core-library-3.45.0.tgz", + "integrity": "sha512-YMuIJl19vQT1+g/OU9mLY6T5ZBT9uDlmeXExDQACpGuxTJW+LHNbk/lRX+eCApQI2eLBlaL4U68r3kZlqwbdmw==", + "dev": true, + "dependencies": { + "@types/node": "12.20.24", + "colors": "~1.2.1", + "fs-extra": "~7.0.1", + "import-lazy": "~4.0.0", + "jju": "~1.4.0", + "resolve": "~1.17.0", + "semver": "~7.3.0", + "timsort": "~0.3.0", + "z-schema": "~5.0.2" + } + }, + "node_modules/@rushstack/node-core-library/node_modules/@types/node": { + "version": "12.20.24", + "resolved": "https://registry.npmjs.org/@types/node/-/node-12.20.24.tgz", + "integrity": "sha512-yxDeaQIAJlMav7fH5AQqPH1u8YIuhYJXYBzxaQ4PifsU0GDO38MSdmEDeRlIxrKbC6NbEaaEHDanWb+y30U8SQ==", + "dev": true + }, + "node_modules/@rushstack/node-core-library/node_modules/colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true, + "engines": { + "node": ">=0.1.90" + } + }, + "node_modules/@rushstack/node-core-library/node_modules/fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/@rushstack/node-core-library/node_modules/jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss=", + "dev": true, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/@rushstack/node-core-library/node_modules/resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "dependencies": { + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/@rushstack/node-core-library/node_modules/universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true, + "engines": { + "node": ">= 4.0.0" + } + }, + "node_modules/@rushstack/rig-package": { + "version": "0.3.7", + "resolved": "https://registry.npmjs.org/@rushstack/rig-package/-/rig-package-0.3.7.tgz", + "integrity": "sha512-pzMsTSeTC8IiZ6EJLr53gGMvhT4oLWH+hxD7907cHyWuIUlEXFtu/2pK25vUQT13nKp5DJCWxXyYoGRk/h6rtA==", + "dev": true, + "dependencies": { + "resolve": "~1.17.0", + "strip-json-comments": "~3.1.1" + } + }, + "node_modules/@rushstack/rig-package/node_modules/resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "dependencies": { + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/@rushstack/ts-command-line": { + "version": "4.10.6", + "resolved": "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.10.6.tgz", + "integrity": "sha512-Y3GkUag39sTIlukDg9mUp8MCHrrlJ27POrBNRQGc/uF+VVgX8M7zMzHch5zP6O1QVquWgD7Engdpn2piPYaS/g==", + "dev": true, + "dependencies": { + "@types/argparse": "1.0.38", + "argparse": "~1.0.9", + "colors": "~1.2.1", + "string-argv": "~0.3.1" + } + }, + "node_modules/@rushstack/ts-command-line/node_modules/colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true, + "engines": { + "node": ">=0.1.90" + } + }, "node_modules/@sinonjs/commons": { "version": "1.8.3", "resolved": "https://registry.npmjs.org/@sinonjs/commons/-/commons-1.8.3.tgz", @@ -943,6 +1224,12 @@ "tsserver": "typescript/bin/tsserver" } }, + "node_modules/@types/argparse": { + "version": "1.0.38", + "resolved": "https://registry.npmjs.org/@types/argparse/-/argparse-1.0.38.tgz", + "integrity": "sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA==", + "dev": true + }, "node_modules/@types/body-parser": { "version": "1.19.2", "resolved": "https://registry.npmjs.org/@types/body-parser/-/body-parser-1.19.2.tgz", @@ -1058,9 +1345,9 @@ "dev": true }, "node_modules/@types/lodash": { - "version": "4.14.179", - "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.179.tgz", - "integrity": "sha512-uwc1x90yCKqGcIOAT6DwOSuxnrAbpkdPsUOZtwrXb4D/6wZs+6qG7QnIawDuZWg0sWpxl+ltIKCaLoMlna678w==" + "version": "4.14.180", + "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.180.tgz", + "integrity": "sha512-XOKXa1KIxtNXgASAnwj7cnttJxS4fksBRywK/9LzRV5YxrF80BXZIGeQSuoESQ/VkUj30Ae0+YcuHc15wJCB2g==" }, "node_modules/@types/lodash.merge": { "version": "4.6.6", @@ -3887,6 +4174,15 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/import-lazy": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/import-lazy/-/import-lazy-4.0.0.tgz", + "integrity": "sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw==", + "dev": true, + "engines": { + "node": ">=8" + } + }, "node_modules/imurmurhash": { "version": "0.1.4", "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz", @@ -4357,6 +4653,12 @@ "node": ">=8" } }, + "node_modules/jju": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/jju/-/jju-1.4.0.tgz", + "integrity": "sha1-o6vicYryQaKykE+EpiWXDzia4yo=", + "dev": true + }, "node_modules/js-tokens": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", @@ -4510,6 +4812,12 @@ "integrity": "sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk=", "dev": true }, + "node_modules/lodash.isequal": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", + "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA=", + "dev": true + }, "node_modules/lodash.merge": { "version": "4.6.2", "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz", @@ -6697,6 +7005,12 @@ "node": ">=0.8" } }, + "node_modules/timsort": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/timsort/-/timsort-0.3.0.tgz", + "integrity": "sha1-QFQRqOfmM5/mTbmiNN4R3DHgK9Q=", + "dev": true + }, "node_modules/tmp": { "version": "0.2.1", "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.1.tgz", @@ -7076,6 +7390,15 @@ "spdx-expression-parse": "^3.0.0" } }, + "node_modules/validator": { + "version": "13.7.0", + "resolved": "https://registry.npmjs.org/validator/-/validator-13.7.0.tgz", + "integrity": "sha512-nYXQLCBkpJ8X6ltALua9dRrZDHVYxjJ1wgskNt1lH9fzGjs3tgojGSCBjmEPwkWS1y29+DrizMTW19Pr9uB2nw==", + "dev": true, + "engines": { + "node": ">= 0.10" + } + }, "node_modules/vary": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", @@ -7319,6 +7642,33 @@ "engines": { "node": ">=10" } + }, + "node_modules/z-schema": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.2.tgz", + "integrity": "sha512-40TH47ukMHq5HrzkeVE40Ad7eIDKaRV2b+Qpi2prLc9X9eFJFzV7tMe5aH12e6avaSS/u5l653EQOv+J9PirPw==", + "dev": true, + "dependencies": { + "lodash.get": "^4.4.2", + "lodash.isequal": "^4.5.0", + "validator": "^13.7.0" + }, + "bin": { + "z-schema": "bin/z-schema" + }, + "engines": { + "node": ">=8.0.0" + }, + "optionalDependencies": { + "commander": "^2.7.1" + } + }, + "node_modules/z-schema/node_modules/commander": { + "version": "2.20.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", + "dev": true, + "optional": true } }, "dependencies": { @@ -7579,9 +7929,9 @@ "dev": true }, "@babel/runtime": { - "version": "7.17.2", - "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.17.2.tgz", - "integrity": "sha512-hzeyJyMA1YGdJTuWU0e/j4wKXrU4OMFvY2MSlaI9B7VQb0r5cxTE3EAIS2Q7Tn2RIcDkRvTA/v2JsAEhxe99uw==", + "version": "7.17.7", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.17.7.tgz", + "integrity": "sha512-L6rvG9GDxaLgFjg41K+5Yv9OMrU98sWe+Ykmc6FDJW/+vYZMhdOMKkISgzptMaERHvS2Y2lw9MDRm2gHhlQQoA==", "requires": { "regenerator-runtime": "^0.13.4" } @@ -7658,9 +8008,9 @@ "dev": true }, "@cucumber/cucumber-expressions": { - "version": "15.0.1", - "resolved": "https://registry.npmjs.org/@cucumber/cucumber-expressions/-/cucumber-expressions-15.0.1.tgz", - "integrity": "sha512-TFUjz20+4OpHXDGXN7fv+JDSYkTvdakz1R/2OEV8gqYAkPUhjx+jeiyDF6C0rPzx9MoD7B3DoPfcfA2nS3Bh4w==", + "version": "15.0.2", + "resolved": "https://registry.npmjs.org/@cucumber/cucumber-expressions/-/cucumber-expressions-15.0.2.tgz", + "integrity": "sha512-ppN9JL1C5lw3InvM7WnoKZV9La5PW5Vr8c/8J0ZGzdlC8Y+PB7kskGzx7/tzl9kGjq7USQ7MZfwFz5el2sB/GA==", "requires": { "regexp-match-indices": "1.0.2" } @@ -7900,6 +8250,138 @@ "integrity": "sha512-ZXRY4jNvVgSVQ8DL3LTcakaAtXwTVUxE81hslsyD2AtoXW/wVob10HkOJ1X/pAlcI7D+2YoZKg5do8G/w6RYgA==", "dev": true }, + "@microsoft/api-documenter": { + "version": "7.15.3", + "resolved": "https://registry.npmjs.org/@microsoft/api-documenter/-/api-documenter-7.15.3.tgz", + "integrity": "sha512-tehv1f/aKwGBQp0sheQofz5NQfa61mvTdAe4IHQnVavsyyK71r+P+CVXWewznPYkqFzzVXaTdrCuNGPU5Yd3mg==", + "dev": true, + "requires": { + "@microsoft/api-extractor-model": "7.15.3", + "@microsoft/tsdoc": "0.13.2", + "@rushstack/node-core-library": "3.45.0", + "@rushstack/ts-command-line": "4.10.6", + "colors": "~1.2.1", + "js-yaml": "~3.13.1", + "resolve": "~1.17.0" + }, + "dependencies": { + "colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true + }, + "js-yaml": { + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "dev": true, + "requires": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + } + }, + "resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "requires": { + "path-parse": "^1.0.6" + } + } + } + }, + "@microsoft/api-extractor": { + "version": "7.19.4", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.19.4.tgz", + "integrity": "sha512-iehC6YA3DGJvxTUaK7HUtQmP6hAQU07+Q/OR8TG4dVR6KpqCi9UPEVk8AgCvQkiK+6FbVEFQTx0qLuYk4EeuHg==", + "dev": true, + "requires": { + "@microsoft/api-extractor-model": "7.15.3", + "@microsoft/tsdoc": "0.13.2", + "@microsoft/tsdoc-config": "~0.15.2", + "@rushstack/node-core-library": "3.45.0", + "@rushstack/rig-package": "0.3.7", + "@rushstack/ts-command-line": "4.10.6", + "colors": "~1.2.1", + "lodash": "~4.17.15", + "resolve": "~1.17.0", + "semver": "~7.3.0", + "source-map": "~0.6.1", + "typescript": "~4.5.2" + }, + "dependencies": { + "colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true + }, + "resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "requires": { + "path-parse": "^1.0.6" + } + }, + "source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true + }, + "typescript": { + "version": "4.5.5", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.5.5.tgz", + "integrity": "sha512-TCTIul70LyWe6IJWT8QSYeA54WQe8EjQFU4wY52Fasj5UKx88LNYKCgBEHcOMOrFF1rKGbD8v/xcNWVUq9SymA==", + "dev": true + } + } + }, + "@microsoft/api-extractor-model": { + "version": "7.15.3", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.15.3.tgz", + "integrity": "sha512-NkSjolmSI7NGvbdz0Y7kjQfdpD+j9E5CwXTxEyjDqxd10MI7GXV8DnAsQ57GFJcgHKgTjf2aUnYfMJ9w3aMicw==", + "dev": true, + "requires": { + "@microsoft/tsdoc": "0.13.2", + "@microsoft/tsdoc-config": "~0.15.2", + "@rushstack/node-core-library": "3.45.0" + } + }, + "@microsoft/tsdoc": { + "version": "0.13.2", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc/-/tsdoc-0.13.2.tgz", + "integrity": "sha512-WrHvO8PDL8wd8T2+zBGKrMwVL5IyzR3ryWUsl0PXgEV0QHup4mTLi0QcATefGI6Gx9Anu7vthPyyyLpY0EpiQg==", + "dev": true + }, + "@microsoft/tsdoc-config": { + "version": "0.15.2", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc-config/-/tsdoc-config-0.15.2.tgz", + "integrity": "sha512-mK19b2wJHSdNf8znXSMYVShAHktVr/ib0Ck2FA3lsVBSEhSI/TfXT7DJQkAYgcztTuwazGcg58ZjYdk0hTCVrA==", + "dev": true, + "requires": { + "@microsoft/tsdoc": "0.13.2", + "ajv": "~6.12.6", + "jju": "~1.4.0", + "resolve": "~1.19.0" + }, + "dependencies": { + "resolve": { + "version": "1.19.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.19.0.tgz", + "integrity": "sha512-rArEXAgsBG4UgRGcynxWIWKFvh/XZCcS8UJdHhwy91zwAvCZIbcs+vAbflgBnNjYMs/i/i+/Ux6IZhML1yPvxg==", + "dev": true, + "requires": { + "is-core-module": "^2.1.0", + "path-parse": "^1.0.6" + } + } + } + }, "@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", @@ -7926,6 +8408,113 @@ "fastq": "^1.6.0" } }, + "@rushstack/node-core-library": { + "version": "3.45.0", + "resolved": "https://registry.npmjs.org/@rushstack/node-core-library/-/node-core-library-3.45.0.tgz", + "integrity": "sha512-YMuIJl19vQT1+g/OU9mLY6T5ZBT9uDlmeXExDQACpGuxTJW+LHNbk/lRX+eCApQI2eLBlaL4U68r3kZlqwbdmw==", + "dev": true, + "requires": { + "@types/node": "12.20.24", + "colors": "~1.2.1", + "fs-extra": "~7.0.1", + "import-lazy": "~4.0.0", + "jju": "~1.4.0", + "resolve": "~1.17.0", + "semver": "~7.3.0", + "timsort": "~0.3.0", + "z-schema": "~5.0.2" + }, + "dependencies": { + "@types/node": { + "version": "12.20.24", + "resolved": "https://registry.npmjs.org/@types/node/-/node-12.20.24.tgz", + "integrity": "sha512-yxDeaQIAJlMav7fH5AQqPH1u8YIuhYJXYBzxaQ4PifsU0GDO38MSdmEDeRlIxrKbC6NbEaaEHDanWb+y30U8SQ==", + "dev": true + }, + "colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true + }, + "fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + }, + "jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss=", + "dev": true, + "requires": { + "graceful-fs": "^4.1.6" + } + }, + "resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "requires": { + "path-parse": "^1.0.6" + } + }, + "universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true + } + } + }, + "@rushstack/rig-package": { + "version": "0.3.7", + "resolved": "https://registry.npmjs.org/@rushstack/rig-package/-/rig-package-0.3.7.tgz", + "integrity": "sha512-pzMsTSeTC8IiZ6EJLr53gGMvhT4oLWH+hxD7907cHyWuIUlEXFtu/2pK25vUQT13nKp5DJCWxXyYoGRk/h6rtA==", + "dev": true, + "requires": { + "resolve": "~1.17.0", + "strip-json-comments": "~3.1.1" + }, + "dependencies": { + "resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "requires": { + "path-parse": "^1.0.6" + } + } + } + }, + "@rushstack/ts-command-line": { + "version": "4.10.6", + "resolved": "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.10.6.tgz", + "integrity": "sha512-Y3GkUag39sTIlukDg9mUp8MCHrrlJ27POrBNRQGc/uF+VVgX8M7zMzHch5zP6O1QVquWgD7Engdpn2piPYaS/g==", + "dev": true, + "requires": { + "@types/argparse": "1.0.38", + "argparse": "~1.0.9", + "colors": "~1.2.1", + "string-argv": "~0.3.1" + }, + "dependencies": { + "colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true + } + } + }, "@sinonjs/commons": { "version": "1.8.3", "resolved": "https://registry.npmjs.org/@sinonjs/commons/-/commons-1.8.3.tgz", @@ -7997,6 +8586,12 @@ "integrity": "sha512-iDlLkdg3sCjUSNdoUCsYM/SXheHrdxHsR6msIkbFDW4pV6gHTMwg/8te/paLtywDjGL4S4ByDdUKA3RbfdBX0g==", "dev": true }, + "@types/argparse": { + "version": "1.0.38", + "resolved": "https://registry.npmjs.org/@types/argparse/-/argparse-1.0.38.tgz", + "integrity": "sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA==", + "dev": true + }, "@types/body-parser": { "version": "1.19.2", "resolved": "https://registry.npmjs.org/@types/body-parser/-/body-parser-1.19.2.tgz", @@ -8112,9 +8707,9 @@ "dev": true }, "@types/lodash": { - "version": "4.14.179", - "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.179.tgz", - "integrity": "sha512-uwc1x90yCKqGcIOAT6DwOSuxnrAbpkdPsUOZtwrXb4D/6wZs+6qG7QnIawDuZWg0sWpxl+ltIKCaLoMlna678w==" + "version": "4.14.180", + "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.180.tgz", + "integrity": "sha512-XOKXa1KIxtNXgASAnwj7cnttJxS4fksBRywK/9LzRV5YxrF80BXZIGeQSuoESQ/VkUj30Ae0+YcuHc15wJCB2g==" }, "@types/lodash.merge": { "version": "4.6.6", @@ -10273,6 +10868,12 @@ "resolve-from": "^4.0.0" } }, + "import-lazy": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/import-lazy/-/import-lazy-4.0.0.tgz", + "integrity": "sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw==", + "dev": true + }, "imurmurhash": { "version": "0.1.4", "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz", @@ -10607,6 +11208,12 @@ "istanbul-lib-report": "^3.0.0" } }, + "jju": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/jju/-/jju-1.4.0.tgz", + "integrity": "sha1-o6vicYryQaKykE+EpiWXDzia4yo=", + "dev": true + }, "js-tokens": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", @@ -10734,6 +11341,12 @@ "integrity": "sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk=", "dev": true }, + "lodash.isequal": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", + "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA=", + "dev": true + }, "lodash.merge": { "version": "4.6.2", "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz", @@ -12376,6 +12989,12 @@ "thenify": ">= 3.1.0 < 4" } }, + "timsort": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/timsort/-/timsort-0.3.0.tgz", + "integrity": "sha1-QFQRqOfmM5/mTbmiNN4R3DHgK9Q=", + "dev": true + }, "tmp": { "version": "0.2.1", "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.1.tgz", @@ -12660,6 +13279,12 @@ "spdx-expression-parse": "^3.0.0" } }, + "validator": { + "version": "13.7.0", + "resolved": "https://registry.npmjs.org/validator/-/validator-13.7.0.tgz", + "integrity": "sha512-nYXQLCBkpJ8X6ltALua9dRrZDHVYxjJ1wgskNt1lH9fzGjs3tgojGSCBjmEPwkWS1y29+DrizMTW19Pr9uB2nw==", + "dev": true + }, "vary": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", @@ -12839,6 +13464,27 @@ "property-expr": "^2.0.4", "toposort": "^2.0.2" } + }, + "z-schema": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.2.tgz", + "integrity": "sha512-40TH47ukMHq5HrzkeVE40Ad7eIDKaRV2b+Qpi2prLc9X9eFJFzV7tMe5aH12e6avaSS/u5l653EQOv+J9PirPw==", + "dev": true, + "requires": { + "commander": "^2.7.1", + "lodash.get": "^4.4.2", + "lodash.isequal": "^4.5.0", + "validator": "^13.7.0" + }, + "dependencies": { + "commander": { + "version": "2.20.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", + "dev": true, + "optional": true + } + } } } } diff --git a/package.json b/package.json index 36edb8fea..815be3ec1 100644 --- a/package.json +++ b/package.json @@ -175,6 +175,10 @@ "import": "./lib/wrapper.mjs", "require": "./lib/index.js" }, + "./api": { + "import": "./lib/api/wrapper.mjs", + "require": "./lib/api/index.js" + }, "./lib/*": { "require": "./lib/*.js" }, @@ -187,7 +191,7 @@ "dependencies": { "@cspotcode/source-map-support": "^0.7.0", "@cucumber/ci-environment": "9.0.0", - "@cucumber/cucumber-expressions": "15.0.1", + "@cucumber/cucumber-expressions": "15.0.2", "@cucumber/gherkin": "22.0.0", "@cucumber/gherkin-streams": "4.0.0", "@cucumber/html-formatter": "18.0.0", @@ -223,6 +227,8 @@ "@cucumber/compatibility-kit": "9.1.2", "@cucumber/message-streams": "3.0.0", "@cucumber/query": "11.0.0", + "@microsoft/api-documenter": "^7.15.3", + "@microsoft/api-extractor": "^7.19.4", "@sinonjs/fake-timers": "9.1.0", "@types/chai": "4.3.0", "@types/dirty-chai": "2.0.2", @@ -275,8 +281,10 @@ "typescript": "4.6.2" }, "scripts": { - "build-local": "genversion --es6 src/version.ts && tsc --build tsconfig.node.json && shx cp src/importer.js lib/ && shx cp src/wrapper.mjs lib/", + "build-local": "genversion --es6 src/version.ts && tsc --build tsconfig.node.json && shx cp src/importer.js lib/ && shx cp src/wrapper.mjs lib/ && shx cp src/api/wrapper.mjs lib/api/", "cck-test": "mocha 'compatibility/**/*_spec.ts'", + "docs:ci": "api-extractor run --verbose", + "docs:local": "api-extractor run --verbose --local && api-documenter markdown --input-folder ./tmp/api-extractor --output-folder ./docs/api", "feature-test": "node ./bin/cucumber-js", "lint-autofix": "eslint --fix \"{compatibility,example,features,scripts,src,test}/**/*.ts\"", "lint-code": "eslint \"{compatibility,example,features,scripts,src,test}/**/*.ts\"", @@ -290,7 +298,7 @@ "pretest-coverage": "npm run build-local", "pretypes-test": "npm run build-local", "test-coverage": "nyc --silent mocha 'src/**/*_spec.ts' 'compatibility/**/*_spec.ts' && nyc --silent --no-clean node ./bin/cucumber-js && nyc report --reporter=lcov", - "test": "npm run lint && npm run types-test && npm run unit-test && npm run cck-test && npm run feature-test", + "test": "npm run lint && npm run docs:ci && npm run types-test && npm run unit-test && npm run cck-test && npm run feature-test", "types-test": "tsd", "unit-test": "mocha 'src/**/*_spec.ts'", "update-dependencies": "npx npm-check-updates --upgrade" diff --git a/reports/cucumber.api.md b/reports/cucumber.api.md new file mode 100644 index 000000000..852bec264 --- /dev/null +++ b/reports/cucumber.api.md @@ -0,0 +1,144 @@ +## API Report File for "@cucumber/cucumber" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +/// + +import { Envelope } from '@cucumber/messages'; +import { Expression } from '@cucumber/cucumber-expressions'; +import http from 'http'; +import * as messages from '@cucumber/messages'; +import { ParameterTypeRegistry } from '@cucumber/cucumber-expressions'; +import { PassThrough } from 'stream'; +import { Transform } from 'stream'; +import { WriteStream } from 'fs'; +import { WriteStream as WriteStream_2 } from 'tty'; + +// @public (undocumented) +export interface ILoadConfigurationOptions { + file?: string; + profiles?: string[]; + // Warning: (ae-forgotten-export) The symbol "IConfiguration" needs to be exported by the entry point index.d.ts + provided?: Partial; +} + +// @public (undocumented) +export interface ILoadSupportOptions { + // (undocumented) + sources: ISourcesCoordinates; + // (undocumented) + support: ISupportCodeCoordinates; +} + +// @public (undocumented) +export interface IResolvedConfiguration { + runConfiguration: IRunConfiguration; + useConfiguration: IConfiguration; +} + +// @public (undocumented) +export interface IRunConfiguration { + // (undocumented) + formats: IRunOptionsFormats; + // (undocumented) + runtime: IRunOptionsRuntime; + // (undocumented) + sources: ISourcesCoordinates; + // (undocumented) + support: ISupportCodeCoordinates; +} + +// @public +export interface IRunEnvironment { + cwd?: string; + env?: NodeJS.ProcessEnv; + stderr?: IFormatterStream; + // Warning: (ae-forgotten-export) The symbol "IFormatterStream" needs to be exported by the entry point index.d.ts + stdout?: IFormatterStream; +} + +// @public (undocumented) +export interface IRunOptions { + // (undocumented) + formats: IRunOptionsFormats; + // (undocumented) + runtime: IRunOptionsRuntime; + // (undocumented) + sources: ISourcesCoordinates; + // (undocumented) + support: ISupportCodeCoordinatesOrLibrary; +} + +// @public (undocumented) +export interface IRunOptionsFormats { + // (undocumented) + files: Record; + // Warning: (ae-forgotten-export) The symbol "FormatOptions" needs to be exported by the entry point index.d.ts + // + // (undocumented) + options: FormatOptions; + // (undocumented) + publish: { + url?: string; + token?: string; + } | false; + // (undocumented) + stdout: string; +} + +// Warning: (ae-forgotten-export) The symbol "IRuntimeOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +export interface IRunOptionsRuntime extends IRuntimeOptions { + // (undocumented) + parallel: number; +} + +// @public +export interface IRunResult { + success: boolean; + // Warning: (ae-forgotten-export) The symbol "ISupportCodeLibrary" needs to be exported by the entry point index.d.ts + support: ISupportCodeLibrary; +} + +// @public (undocumented) +export interface ISourcesCoordinates { + // (undocumented) + defaultDialect: string; + // (undocumented) + names: string[]; + // Warning: (ae-forgotten-export) The symbol "PickleOrder" needs to be exported by the entry point index.d.ts + // + // (undocumented) + order: PickleOrder; + // (undocumented) + paths: string[]; + // (undocumented) + tagExpression: string; +} + +// @public (undocumented) +export interface ISupportCodeCoordinates { + // (undocumented) + importPaths: string[]; + // (undocumented) + requireModules: string[]; + // (undocumented) + requirePaths: string[]; +} + +// @public (undocumented) +export type ISupportCodeCoordinatesOrLibrary = ISupportCodeCoordinates | ISupportCodeLibrary; + +// @public +export function loadConfiguration(options?: ILoadConfigurationOptions, environment?: IRunEnvironment): Promise; + +// @public +export function loadSupport(options: ILoadSupportOptions, environment?: IRunEnvironment): Promise; + +// @public +export function runCucumber(configuration: IRunOptions, environment?: IRunEnvironment, onMessage?: (message: Envelope) => void): Promise; + +``` diff --git a/src/api/convert_configuration.ts b/src/api/convert_configuration.ts index 595f68669..63735cf22 100644 --- a/src/api/convert_configuration.ts +++ b/src/api/convert_configuration.ts @@ -3,12 +3,12 @@ import { isTruthyString, OptionSplitter, } from '../configuration' -import { IRunnableConfiguration } from './types' +import { IRunConfiguration } from './types' export async function convertConfiguration( flatConfiguration: IConfiguration, env: NodeJS.ProcessEnv -): Promise { +): Promise { return { sources: { paths: flatConfiguration.paths, diff --git a/src/api/environment.ts b/src/api/environment.ts new file mode 100644 index 000000000..e34ac849a --- /dev/null +++ b/src/api/environment.ts @@ -0,0 +1,16 @@ +import { IRunEnvironment } from './types' + +export function mergeEnvironment( + provided: IRunEnvironment +): Required { + return Object.assign( + {}, + { + cwd: process.cwd(), + stdout: process.stdout, + stderr: process.stderr, + env: process.env, + }, + provided + ) +} diff --git a/src/api/index.ts b/src/api/index.ts index a4943a48e..51dbcef03 100644 --- a/src/api/index.ts +++ b/src/api/index.ts @@ -1,5 +1,8 @@ -/* -Anything exported here will be publicly available via `@cucumber/cucumber/api` +/** + * Cucumber for JavaScript + * + * @remarks These docs cover the API used for running Cucumber programmatically. The entry point is `@cucumber/cucumber/api`. + * @packageDocumentation */ export * from './load_configuration' diff --git a/src/api/load_configuration.ts b/src/api/load_configuration.ts index bd86d50cf..8e4780462 100644 --- a/src/api/load_configuration.ts +++ b/src/api/load_configuration.ts @@ -1,22 +1,30 @@ -import { IRunEnvironment, IResolvedConfiguration } from './types' +import { + IRunEnvironment, + IResolvedConfiguration, + ILoadConfigurationOptions, +} from './types' import { locateFile } from '../configuration/locate_file' import { DEFAULT_CONFIGURATION, fromFile, - IConfiguration, mergeConfigurations, } from '../configuration' import { validateConfiguration } from '../configuration/validate_configuration' import { convertConfiguration } from './convert_configuration' +import { mergeEnvironment } from './environment' +/** + * Load user-authored configuration to be used in a test run. + * + * @public + * @param options - Coordinates required to find configuration. + * @param environment - Project environment. + */ export async function loadConfiguration( - options: { - file?: string - profiles?: string[] - provided?: Partial - }, - { cwd = process.cwd(), env = process.env }: Partial + options: ILoadConfigurationOptions = {}, + environment: IRunEnvironment = {} ): Promise { + const { cwd, env } = mergeEnvironment(environment) const configFile = options.file ?? locateFile(cwd) const profileConfiguration = configFile ? await fromFile(cwd, configFile, options.profiles) @@ -29,7 +37,7 @@ export async function loadConfiguration( validateConfiguration(original) const runnable = await convertConfiguration(original, env) return { - original, - runnable, + useConfiguration: original, + runConfiguration: runnable, } } diff --git a/src/api/load_support.ts b/src/api/load_support.ts index 30aef8cd2..3a1adfe49 100644 --- a/src/api/load_support.ts +++ b/src/api/load_support.ts @@ -1,22 +1,32 @@ import { IdGenerator } from '@cucumber/messages' -import { IRunEnvironment, IRunnableConfiguration } from './types' +import { ILoadSupportOptions, IRunEnvironment } from './types' import { resolvePaths } from './paths' import { getSupportCodeLibrary } from './support' +import { mergeEnvironment } from './environment' +import { ISupportCodeLibrary } from '../support_code_library_builder/types' +/** + * Load support code for use in test runs. + * + * @public + * @param options - Subset of `IRunnableConfiguration` required to find the support code. + * @param environment - Project environment. + */ export async function loadSupport( - configuration: Pick, - { cwd = process.cwd() }: Partial -) { + options: ILoadSupportOptions, + environment: IRunEnvironment = {} +): Promise { + const { cwd } = mergeEnvironment(environment) const newId = IdGenerator.uuid() const { requirePaths, importPaths } = await resolvePaths( cwd, - configuration.sources, - configuration.support + options.sources, + options.support ) return await getSupportCodeLibrary({ cwd, newId, - requireModules: configuration.support.requireModules, + requireModules: options.support.requireModules, requirePaths, importPaths, }) diff --git a/src/api/paths.ts b/src/api/paths.ts index 2516329a8..f6ecba74f 100644 --- a/src/api/paths.ts +++ b/src/api/paths.ts @@ -2,8 +2,7 @@ import { promisify } from 'util' import glob from 'glob' import path from 'path' import fs from 'mz/fs' -import { ISourcesCoordinates } from './types' -import { ISupportCodeCoordinates } from '../support_code_library_builder/types' +import { ISourcesCoordinates, ISupportCodeCoordinates } from './types' export async function resolvePaths( cwd: string, diff --git a/src/api/run_cucumber.ts b/src/api/run_cucumber.ts index 6d05a7d78..f279c41c5 100644 --- a/src/api/run_cucumber.ts +++ b/src/api/run_cucumber.ts @@ -8,7 +8,7 @@ import { } from '../cli/helpers' import { GherkinStreams } from '@cucumber/gherkin-streams' import PickleFilter from '../pickle_filter' -import { IRunConfiguration, IRunEnvironment, IRunResult } from './types' +import { IRunOptions, IRunEnvironment, IRunResult } from './types' import { resolvePaths } from './paths' import { makeRuntime } from './runtime' import { initializeFormatters } from './formatters' @@ -16,17 +16,22 @@ import { getSupportCodeLibrary } from './support' import { Console } from 'console' import * as messages from '@cucumber/messages' import { doesHaveValue } from '../value_checker' +import { mergeEnvironment } from './environment' +/** + * Execute a Cucumber test run. + * + * @public + * @param configuration - Configuration loaded from `loadConfiguration`. + * @param environment - Project environment. + * @param onMessage - Callback fired each time Cucumber emits a message. + */ export async function runCucumber( - configuration: IRunConfiguration, - { - cwd = process.cwd(), - stdout = process.stdout, - stderr = process.stderr, - env = process.env, - }: Partial, + configuration: IRunOptions, + environment: IRunEnvironment = {}, onMessage?: (message: Envelope) => void ): Promise { + const { cwd, stdout, stderr, env } = mergeEnvironment(environment) const logger = new Console(stdout, stderr) const newId = IdGenerator.uuid() diff --git a/src/api/run_cucumber_spec.ts b/src/api/run_cucumber_spec.ts index b1880abf1..6215277b0 100644 --- a/src/api/run_cucumber_spec.ts +++ b/src/api/run_cucumber_spec.ts @@ -35,14 +35,14 @@ async function setupEnvironment(): Promise> { return { cwd, stdout } } -async function teardownEnvironment(environment: Partial) { +async function teardownEnvironment(environment: IRunEnvironment) { await fs.rmdir(environment.cwd, { recursive: true }) environment.stdout.end() } describe('runCucumber', () => { describe('preloading support code', () => { - let environment: Partial + let environment: IRunEnvironment beforeEach(async () => { environment = await setupEnvironment() }) @@ -50,10 +50,12 @@ describe('runCucumber', () => { it('should be able to load support code upfront and supply it to runCucumber', async () => { const messages: Envelope[] = [] - const { runnable } = await loadConfiguration({}, environment) - const support = await loadSupport(runnable, environment) - await runCucumber({ ...runnable, support }, environment, (envelope) => - messages.push(envelope) + const { runConfiguration } = await loadConfiguration({}, environment) + const support = await loadSupport(runConfiguration, environment) + await runCucumber( + { ...runConfiguration, support }, + environment, + (envelope) => messages.push(envelope) ) const testStepFinishedEnvelopes = messages.filter( (envelope) => envelope.testStepFinished @@ -70,7 +72,7 @@ describe('runCucumber', () => { }) describe('reusing support code across runs', () => { - let environment: Partial + let environment: IRunEnvironment beforeEach(async () => { environment = await setupEnvironment() }) @@ -78,12 +80,16 @@ describe('runCucumber', () => { it('successfully executes 2 test runs', async () => { const messages: Envelope[] = [] - const { runnable } = await loadConfiguration({}, environment) - const { support } = await runCucumber(runnable, environment, (envelope) => - messages.push(envelope) + const { runConfiguration } = await loadConfiguration({}, environment) + const { support } = await runCucumber( + runConfiguration, + environment, + (envelope) => messages.push(envelope) ) - await runCucumber({ ...runnable, support }, environment, (envelope) => - messages.push(envelope) + await runCucumber( + { ...runConfiguration, support }, + environment, + (envelope) => messages.push(envelope) ) const testStepFinishedEnvelopes = messages.filter( diff --git a/src/api/types.ts b/src/api/types.ts index b58238240..576428a32 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -1,12 +1,44 @@ -import { - ISupportCodeCoordinates, - ISupportCodeLibrary, -} from '../support_code_library_builder/types' +import { ISupportCodeLibrary } from '../support_code_library_builder/types' import { FormatOptions, IFormatterStream } from '../formatter' import { PickleOrder } from '../models/pickle_order' import { IRuntimeOptions } from '../runtime' import { IConfiguration } from '../configuration' +/** + * @public + */ +export interface ILoadConfigurationOptions { + /** + * Path to load configuration file from (defaults to `cucumber.(js|cjs|mjs|json)` if omitted). + */ + file?: string + /** + * Zero or more profile names from which to source configuration (if omitted or empty, the `default` profile will be used). + */ + profiles?: string[] + /** + * Ad-hoc configuration options to be applied over the top of whatever is loaded from the configuration file/profiles. + */ + provided?: Partial +} + +/** + * @public + */ +export interface IResolvedConfiguration { + /** + * The final flat configuration object resolved from the configuration file/profiles plus any extra provided. + */ + useConfiguration: IConfiguration + /** + * The format that can be passed into `runCucumber`. + */ + runConfiguration: IRunConfiguration +} + +/** + * @public + */ export interface ISourcesCoordinates { defaultDialect: string paths: string[] @@ -15,8 +47,33 @@ export interface ISourcesCoordinates { order: PickleOrder } -export type IRunOptionsRuntime = IRuntimeOptions & { parallel: number } +/** + * @public + */ +export interface ISupportCodeCoordinates { + requireModules: string[] + requirePaths: string[] + importPaths: string[] +} + +/** + * @public + */ +export interface ILoadSupportOptions { + sources: ISourcesCoordinates + support: ISupportCodeCoordinates +} + +/** + * @public + */ +export interface IRunOptionsRuntime extends IRuntimeOptions { + parallel: number +} +/** + * @public + */ export interface IRunOptionsFormats { stdout: string files: Record @@ -29,33 +86,69 @@ export interface IRunOptionsFormats { options: FormatOptions } -export interface IRunnableConfiguration { +/** + * @public + */ +export interface IRunConfiguration { sources: ISourcesCoordinates support: ISupportCodeCoordinates runtime: IRunOptionsRuntime formats: IRunOptionsFormats } -export interface IRunConfiguration { +/** + * @public + */ +export type ISupportCodeCoordinatesOrLibrary = + | ISupportCodeCoordinates + | ISupportCodeLibrary + +/** + * @public + */ +export interface IRunOptions { sources: ISourcesCoordinates - support: ISupportCodeCoordinates | ISupportCodeLibrary + support: ISupportCodeCoordinatesOrLibrary runtime: IRunOptionsRuntime formats: IRunOptionsFormats } +/** + * Contextual data about the project environment. + * + * @public + */ export interface IRunEnvironment { - cwd: string - stdout: IFormatterStream - stderr: IFormatterStream - env: NodeJS.ProcessEnv -} - -export interface IResolvedConfiguration { - original: IConfiguration - runnable: IRunnableConfiguration + /** + * Working directory for the project (defaults to `process.cwd()` if omitted). + */ + cwd?: string + /** + * Writable stream where the test run's main output is written (defaults to `process.stdout` if omitted). + */ + stdout?: IFormatterStream + /** + * Writable stream where the test run's warning/error output is written (defaults to `process.stderr` if omitted). + */ + stderr?: IFormatterStream + /** + * Environment variables (defaults to `process.env` if omitted). + */ + env?: NodeJS.ProcessEnv } +/** + * Result of a Cucumber test run. + * + * @public + */ export interface IRunResult { + /** + * Whether the test run was overall successful i.e. no failed scenarios. The exact meaning can vary based on the `strict` configuration option. + */ success: boolean + /** + * The support code library that was used in the test run; can be reused in subsequent `runCucumber` calls. + */ support: ISupportCodeLibrary } diff --git a/src/api/wrapper.mjs b/src/api/wrapper.mjs new file mode 100644 index 000000000..f34a7ca7a --- /dev/null +++ b/src/api/wrapper.mjs @@ -0,0 +1,5 @@ +import api from './index.js' + +export const loadConfiguration = api.loadConfiguration +export const loadSupport = api.loadSupport +export const runCucumber = api.runCucumber diff --git a/src/cli/index.ts b/src/cli/index.ts index 459ebe92e..614a08222 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -64,18 +64,19 @@ export default class Cli { stderr: this.stderr, env: this.env, } - const { original: configuration, runnable } = await loadConfiguration( - { - file: options.config, - profiles: options.profile, - provided: argvConfiguration, - }, - environment - ) - const { success } = await runCucumber(runnable, environment) + const { useConfiguration: configuration, runConfiguration } = + await loadConfiguration( + { + file: options.config, + profiles: options.profile, + provided: argvConfiguration, + }, + environment + ) + const { success } = await runCucumber(runConfiguration, environment) return { shouldAdvertisePublish: - !runnable.formats.publish && + !runConfiguration.formats.publish && !configuration.publishQuiet && !isTruthyString(this.env.CUCUMBER_PUBLISH_QUIET), shouldExitImmediately: configuration.forceExit,