Skip to content

Commit 9e31198

Browse files
davidjgossaurelien-reeves
davidjgoss
and
aurelien-reeves
authored
api: clean up, add docs, add entry point (#1955)
* test generated docs * add metadata to entry point, regenerate * add tooling * bump cucumber-expressions to fix issue * combine in a single `docs` script and tell dependency-lint.yml * regenerate docs * rework directories * improve docs * add entry point at /api * runtime options to extend * get the docs in reasonable shape; make naming consistent, split out some types/interfaces as needed * get the docs in reasonable shape; make naming consistent, split out some types/interfaces as needed * refactor scripts, add a ci one * fix api-extractor warning for now * use @public * rework tooling, add guidance to CONTRIBUTING.md * write some docs, make some stuff optional where possible * simplify dir structure * add changelog entry * link to new doc in changelog entry * rename interfaces and properties per review feedback * fix hand-written doc * Update docs/javascript_api.md Co-authored-by: Aurélien Reeves <[email protected]> * Update javascript_api.md Co-authored-by: Aurélien Reeves <[email protected]>
1 parent cc633c5 commit 9e31198

File tree

71 files changed

+1890
-95
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+1890
-95
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO
1818
([#1136](https://github.com/cucumber/cucumber-js/issues/1136)
1919
[#1721](https://github.com/cucumber/cucumber-js/pull/1721))
2020
- 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))
21+
- New API for running Cucumber programmatically (see [documentation](./docs/javascript_api.md)) ([#1955](https://github.com/cucumber/cucumber-js/pull/1955))
2122

2223
### Fixed
2324
- Warn users who are on an unsupported node version ([#1922](https://github.com/cucumber/cucumber-js/pull/1922))

‎CONTRIBUTING.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,14 +41,22 @@ Type `npm run` or see the `package.json` scripts section for how to run each cat
4141
* feature tests - `npm run feature-test`
4242
* cucumber-js tests itself
4343

44+
## API Documentation
45+
46+
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.
47+
4448
## Internals
4549

4650
### Project Structure
4751

4852
```
4953
└── src
5054
│
51-
├── cli # argv parsing, reading files
55+
├── api # main runCucumber function etc
56+
│
57+
├── cli # executing from argv
58+
│
59+
├── configuration # loading, merging, validating configuration
5260
│
5361
├── formatter # displaying the results
5462
│

‎api-extractor.json

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
3+
"mainEntryPointFilePath": "<projectFolder>/lib/api/index.d.ts",
4+
"compiler": {
5+
},
6+
"apiReport": {
7+
"enabled": true,
8+
"reportFolder": "<projectFolder>/reports/",
9+
"reportTempFolder": "<projectFolder>/tmp/api-extractor/"
10+
},
11+
"docModel": {
12+
"enabled": true,
13+
"apiJsonFilePath": "<projectFolder>/tmp/api-extractor/<unscopedPackageName>.api.json"
14+
},
15+
"dtsRollup": {
16+
"enabled": false
17+
},
18+
"messages": {
19+
"extractorMessageReporting": {
20+
"ae-forgotten-export": {
21+
"logLevel": "none"
22+
}
23+
}
24+
}
25+
}

‎compatibility/cck_spec.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import { ignorableKeys } from '../features/support/formatter_output_helpers'
99
import * as messages from '@cucumber/messages'
1010
import * as messageStreams from '@cucumber/message-streams'
1111
import util from 'util'
12-
import { runCucumber, IRunnableConfiguration } from '../src/api'
12+
import { runCucumber, IRunConfiguration } from '../src/api'
1313
import { Envelope } from '@cucumber/messages'
1414

1515
const asyncPipeline = util.promisify(pipeline)
@@ -29,7 +29,7 @@ describe('Cucumber Compatibility Kit', () => {
2929
const actualMessages: Envelope[] = []
3030
const stdout = new PassThrough()
3131
const stderr = new PassThrough()
32-
const runConfiguration: IRunnableConfiguration = {
32+
const runConfiguration: IRunConfiguration = {
3333
sources: {
3434
defaultDialect: 'en',
3535
paths: [`${CCK_FEATURES_PATH}/${suiteName}/${suiteName}${extension}`],

‎dependency-lint.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ executedModules:
55
npmScripts:
66
dev:
77
- build
8+
- docs:ci
9+
- docs:local
810
- lint
911
- publish
1012
- test

‎docs/api/cucumber.iloadconfigurationoptions.file.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) &gt; [file](./cucumber.iloadconfigurationoptions.file.md)
4+
5+
## ILoadConfigurationOptions.file property
6+
7+
Path to load configuration file from (defaults to `cucumber.(js|cjs|mjs|json)` if omitted).
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
file?: string;
13+
```

‎docs/api/cucumber.iloadconfigurationoptions.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md)
4+
5+
## ILoadConfigurationOptions interface
6+
7+
8+
<b>Signature:</b>
9+
10+
```typescript
11+
export interface ILoadConfigurationOptions
12+
```
13+
14+
## Properties
15+
16+
| Property | Type | Description |
17+
| --- | --- | --- |
18+
| [file?](./cucumber.iloadconfigurationoptions.file.md) | string | <i>(Optional)</i> Path to load configuration file from (defaults to <code>cucumber.(js&#124;cjs&#124;mjs&#124;json)</code> if omitted). |
19+
| [profiles?](./cucumber.iloadconfigurationoptions.profiles.md) | string\[\] | <i>(Optional)</i> Zero or more profile names from which to source configuration (if omitted or empty, the <code>default</code> profile will be used). |
20+
| [provided?](./cucumber.iloadconfigurationoptions.provided.md) | Partial&lt;IConfiguration&gt; | <i>(Optional)</i> Ad-hoc configuration options to be applied over the top of whatever is loaded from the configuration file/profiles. |
21+

‎docs/api/cucumber.iloadconfigurationoptions.profiles.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) &gt; [profiles](./cucumber.iloadconfigurationoptions.profiles.md)
4+
5+
## ILoadConfigurationOptions.profiles property
6+
7+
Zero or more profile names from which to source configuration (if omitted or empty, the `default` profile will be used).
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
profiles?: string[];
13+
```

‎docs/api/cucumber.iloadconfigurationoptions.provided.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadConfigurationOptions](./cucumber.iloadconfigurationoptions.md) &gt; [provided](./cucumber.iloadconfigurationoptions.provided.md)
4+
5+
## ILoadConfigurationOptions.provided property
6+
7+
Ad-hoc configuration options to be applied over the top of whatever is loaded from the configuration file/profiles.
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
provided?: Partial<IConfiguration>;
13+
```

‎docs/api/cucumber.iloadsupportoptions.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadSupportOptions](./cucumber.iloadsupportoptions.md)
4+
5+
## ILoadSupportOptions interface
6+
7+
8+
<b>Signature:</b>
9+
10+
```typescript
11+
export interface ILoadSupportOptions
12+
```
13+
14+
## Properties
15+
16+
| Property | Type | Description |
17+
| --- | --- | --- |
18+
| [sources](./cucumber.iloadsupportoptions.sources.md) | [ISourcesCoordinates](./cucumber.isourcescoordinates.md) | |
19+
| [support](./cucumber.iloadsupportoptions.support.md) | [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) | |
20+

‎docs/api/cucumber.iloadsupportoptions.sources.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) &gt; [sources](./cucumber.iloadsupportoptions.sources.md)
4+
5+
## ILoadSupportOptions.sources property
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
sources: ISourcesCoordinates;
11+
```

‎docs/api/cucumber.iloadsupportoptions.support.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [ILoadSupportOptions](./cucumber.iloadsupportoptions.md) &gt; [support](./cucumber.iloadsupportoptions.support.md)
4+
5+
## ILoadSupportOptions.support property
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
support: ISupportCodeCoordinates;
11+
```

‎docs/api/cucumber.iresolvedconfiguration.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md)
4+
5+
## IResolvedConfiguration interface
6+
7+
8+
<b>Signature:</b>
9+
10+
```typescript
11+
export interface IResolvedConfiguration
12+
```
13+
14+
## Properties
15+
16+
| Property | Type | Description |
17+
| --- | --- | --- |
18+
| [runConfiguration](./cucumber.iresolvedconfiguration.runconfiguration.md) | [IRunConfiguration](./cucumber.irunconfiguration.md) | The format that can be passed into <code>runCucumber</code>. |
19+
| [useConfiguration](./cucumber.iresolvedconfiguration.useconfiguration.md) | IConfiguration | The final flat configuration object resolved from the configuration file/profiles plus any extra provided. |
20+

‎docs/api/cucumber.iresolvedconfiguration.runconfiguration.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md) &gt; [runConfiguration](./cucumber.iresolvedconfiguration.runconfiguration.md)
4+
5+
## IResolvedConfiguration.runConfiguration property
6+
7+
The format that can be passed into `runCucumber`<!-- -->.
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
runConfiguration: IRunConfiguration;
13+
```

‎docs/api/cucumber.iresolvedconfiguration.useconfiguration.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IResolvedConfiguration](./cucumber.iresolvedconfiguration.md) &gt; [useConfiguration](./cucumber.iresolvedconfiguration.useconfiguration.md)
4+
5+
## IResolvedConfiguration.useConfiguration property
6+
7+
The final flat configuration object resolved from the configuration file/profiles plus any extra provided.
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
useConfiguration: IConfiguration;
13+
```

‎docs/api/cucumber.irunconfiguration.formats.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunConfiguration](./cucumber.irunconfiguration.md) &gt; [formats](./cucumber.irunconfiguration.formats.md)
4+
5+
## IRunConfiguration.formats property
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
formats: IRunOptionsFormats;
11+
```

‎docs/api/cucumber.irunconfiguration.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunConfiguration](./cucumber.irunconfiguration.md)
4+
5+
## IRunConfiguration interface
6+
7+
8+
<b>Signature:</b>
9+
10+
```typescript
11+
export interface IRunConfiguration
12+
```
13+
14+
## Properties
15+
16+
| Property | Type | Description |
17+
| --- | --- | --- |
18+
| [formats](./cucumber.irunconfiguration.formats.md) | [IRunOptionsFormats](./cucumber.irunoptionsformats.md) | |
19+
| [runtime](./cucumber.irunconfiguration.runtime.md) | [IRunOptionsRuntime](./cucumber.irunoptionsruntime.md) | |
20+
| [sources](./cucumber.irunconfiguration.sources.md) | [ISourcesCoordinates](./cucumber.isourcescoordinates.md) | |
21+
| [support](./cucumber.irunconfiguration.support.md) | [ISupportCodeCoordinates](./cucumber.isupportcodecoordinates.md) | |
22+

‎docs/api/cucumber.irunconfiguration.runtime.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunConfiguration](./cucumber.irunconfiguration.md) &gt; [runtime](./cucumber.irunconfiguration.runtime.md)
4+
5+
## IRunConfiguration.runtime property
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
runtime: IRunOptionsRuntime;
11+
```

‎docs/api/cucumber.irunconfiguration.sources.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunConfiguration](./cucumber.irunconfiguration.md) &gt; [sources](./cucumber.irunconfiguration.sources.md)
4+
5+
## IRunConfiguration.sources property
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
sources: ISourcesCoordinates;
11+
```

‎docs/api/cucumber.irunconfiguration.support.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunConfiguration](./cucumber.irunconfiguration.md) &gt; [support](./cucumber.irunconfiguration.support.md)
4+
5+
## IRunConfiguration.support property
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
support: ISupportCodeCoordinates;
11+
```

‎docs/api/cucumber.irunenvironment.cwd.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md) &gt; [cwd](./cucumber.irunenvironment.cwd.md)
4+
5+
## IRunEnvironment.cwd property
6+
7+
Working directory for the project (defaults to `process.cwd()` if omitted).
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
cwd?: string;
13+
```

‎docs/api/cucumber.irunenvironment.env.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md) &gt; [env](./cucumber.irunenvironment.env.md)
4+
5+
## IRunEnvironment.env property
6+
7+
Environment variables (defaults to `process.env` if omitted).
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
env?: NodeJS.ProcessEnv;
13+
```

‎docs/api/cucumber.irunenvironment.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md)
4+
5+
## IRunEnvironment interface
6+
7+
Contextual data about the project environment.
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
export interface IRunEnvironment
13+
```
14+
15+
## Properties
16+
17+
| Property | Type | Description |
18+
| --- | --- | --- |
19+
| [cwd?](./cucumber.irunenvironment.cwd.md) | string | <i>(Optional)</i> Working directory for the project (defaults to <code>process.cwd()</code> if omitted). |
20+
| [env?](./cucumber.irunenvironment.env.md) | NodeJS.ProcessEnv | <i>(Optional)</i> Environment variables (defaults to <code>process.env</code> if omitted). |
21+
| [stderr?](./cucumber.irunenvironment.stderr.md) | IFormatterStream | <i>(Optional)</i> Writable stream where the test run's warning/error output is written (defaults to <code>process.stderr</code> if omitted). |
22+
| [stdout?](./cucumber.irunenvironment.stdout.md) | IFormatterStream | <i>(Optional)</i> Writable stream where the test run's main output is written (defaults to <code>process.stdout</code> if omitted). |
23+

‎docs/api/cucumber.irunenvironment.stderr.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md) &gt; [stderr](./cucumber.irunenvironment.stderr.md)
4+
5+
## IRunEnvironment.stderr property
6+
7+
Writable stream where the test run's warning/error output is written (defaults to `process.stderr` if omitted).
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
stderr?: IFormatterStream;
13+
```

‎docs/api/cucumber.irunenvironment.stdout.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@cucumber/cucumber](./cucumber.md) &gt; [IRunEnvironment](./cucumber.irunenvironment.md) &gt; [stdout](./cucumber.irunenvironment.stdout.md)
4+
5+
## IRunEnvironment.stdout property
6+
7+
Writable stream where the test run's main output is written (defaults to `process.stdout` if omitted).
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
stdout?: IFormatterStream;
13+
```

0 commit comments

Comments
 (0)