Skip to content

Commit

Permalink
fix: drop promiseConfig option
Browse files Browse the repository at this point in the history 
BREAKING CHANGE:
drop promiseConfig option and parseConfig return Promise
  • Loading branch information
@anthony-redFox
anthony-redFox committed Oct 30, 2023
1 parent baabb26 commit 4e3efeb
Show file tree
Hide file tree
Showing 8 changed files with 174 additions and 507 deletions.
232 changes: 66 additions & 166 deletions docs/dev/04-public-api.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
Most of the time, you will be using Karma directly from the command line.
You can, however, call Karma programmatically from your node module. Here is the public API.


## karma.Server(options, [callback=process.exit])

### `constructor`
Expand All @@ -10,42 +9,24 @@ You can, however, call Karma programmatically from your node module. Here is the

#### Usage

Notice the capital 'S' on `require('karma').Server`.

##### Deprecated Behavior

The following still works, but the way it behaves is deprecated and will be
changed in a future major version.

```javascript
var Server = require('karma').Server
var karmaConfig = {port: 9876}
var server = new Server(karmaConfig, function(exitCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})
```

##### New Behavior
Notice the capital 'S' on `require('karma').Server`.

```javascript
const karma = require('karma')
const parseConfig = karma.config.parseConfig
const Server = karma.Server

parseConfig(
null,
{ port: 9876 },
{ promiseConfig: true }
).then(
parseConfig(null, { port: 9876 }).then(
(karmaConfig) => {
const server = new Server(karmaConfig, function doneCallback(exitCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})
},
(rejectReason) => { /* respond to the rejection reason error */ }
);
(rejectReason) => {
/* respond to the rejection reason error */
}
)
```

### `server.start()`
Expand Down Expand Up @@ -83,47 +64,53 @@ server.on('browser_register', function (browser) {
```

### `listening`

**Arguments:**

* `port`: Port number
- `port`: Port number

Begin accepting connections on the specified port.

### `browser_register`

**Arguments:**

* `browser`: The browser instance
- `browser`: The browser instance

A new browser was opened, but is not ready yet.

### `browser_error`

**Arguments:**

* `browser`: The browser instance
* `error`: The error that occurred
- `browser`: The browser instance
- `error`: The error that occurred

There was an error in this browser instance.

### `browser_start`

**Arguments:**

* `browser`: The browser instance
* `info`: Details about the run
- `browser`: The browser instance
- `info`: Details about the run

A test run is beginning in this browser.

### `browser_complete`

**Arguments:**

* `browser`: The browser instance
* `result`: Test results
- `browser`: The browser instance
- `result`: Test results

A test run has completed in this browser.

### `browsers_change`

**Arguments:**

* `browsers`: A collection of browser instances
- `browsers`: A collection of browser instances

The list of browsers has changed.

Expand All @@ -132,17 +119,19 @@ The list of browsers has changed.
All browsers are ready for execution

### `run_start`

**Arguments:**

* `browsers`: A collection of browser instances on which tests are executed
- `browsers`: A collection of browser instances on which tests are executed

A test run starts.

### `run_complete`

**Arguments:**

* `browsers`: A collection of browser instances
* `results`: A list of results
- `browsers`: A collection of browser instances
- `results`: A list of results

This event gets triggered whenever all the browsers, which belong to a test run, finish. For example, on a run that has 3 browsers, one would expect 3 `browser_complete` events before the `run_complete` one.

Expand All @@ -156,37 +145,23 @@ The equivalent of `karma run`.

#### Usage

##### Deprecated Behavior

The following still works, but the way it behaves is deprecated and will be
changed in a future major version.

```javascript
var runner = require('karma').runner
runner.run({port: 9876}, function(exitCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})
```

##### New Behavior

```javascript
const karma = require('karma')

karma.config.parseConfig(
null,
{ port: 9876 },
{ promiseConfig: true }
).then(
karma.config.parseConfig(null, { port: 9876 }).then(
(karmaConfig) => {
karma.runner.run(karmaConfig, function doneCallback(exitCode, possibleErrorCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})
karma.runner.run(
karmaConfig,
function doneCallback(exitCode, possibleErrorCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
}
)
},
(rejectReason) => { /* respond to the rejection reason error */ }
);
(rejectReason) => {
/* respond to the rejection reason error */
}
)
```

#### `callback` argument
Expand All @@ -204,7 +179,7 @@ the reporter output as a `Buffer` object.
You may listen for that event to print the reporter output to the console:

```javascript
runner.run({port: 9876}).on('progress', function(data) {
runner.run({ port: 9876 }).on('progress', function (data) {
process.stdout.write(data)
})
```
Expand All @@ -218,41 +193,25 @@ This function will signal a running server to stop. The equivalent of

#### Usage

##### Deprecated Behavior

The following still works, but the way it behaves is deprecated and will be
changed in a future major version.

```javascript
var stopper = require('karma').stopper
stopper.stop({port: 9876}, function(exitCode) {
if (exitCode === 0) {
console.log('Server stop as initiated')
}
process.exit(exitCode)
})
```

##### New Behavior

```javascript
const karma = require('karma')

karma.config.parseConfig(
null,
{ port: 9876 },
{ promiseConfig: true }
).then(
karma.config.parseConfig(null, { port: 9876 }).then(
(karmaConfig) => {
karma.stopper.stop(karmaConfig, function doneCallback(exitCode, possibleErrorCode) {
if (exitCode === 0) {
console.log('Server stop as initiated')
karma.stopper.stop(
karmaConfig,
function doneCallback(exitCode, possibleErrorCode) {
if (exitCode === 0) {
console.log('Server stop as initiated')
}
process.exit(exitCode)
}
process.exit(exitCode)
})
)
},
(rejectReason) => { /* respond to the rejection reason error */ }
);
(rejectReason) => {
/* respond to the rejection reason error */
}
)
```

#### `callback` argument
Expand All @@ -264,50 +223,28 @@ the error callback.

## karma.config

### `config.parseConfig([configFilePath], [cliOptions], [parseOptions])`
### `config.parseConfig([configFilePath], [cliOptions])`

This function will load given config file and returns a filled config object.
This can be useful if you want to integrate karma into another tool and want to load
the karma config while honoring the karma defaults.

#### Usage

##### Deprecated Behavior

The following still works, but the way it behaves is deprecated and will be
changed in a future major version.

```javascript
const cfg = require('karma').config;
const path = require('path');
const cfg = require('karma').config
const path = require('path')
// Read karma.conf.js, but override port with 1337
const karmaConfig = cfg.parseConfig(
path.resolve('./karma.conf.js'),
{ port: 1337 }
);
```

The new behavior in the future will involve throwing exceptions instead of
exiting the process and asynchronous config files will be supported through the
use of promises.

##### New Behavior

```javascript
const cfg = require('karma').config;
const path = require('path');
// Read karma.conf.js, but override port with 1337
cfg.parseConfig(
path.resolve('./karma.conf.js'),
{ port: 1337 },
{ promiseConfig: true }
).then(
(karmaConfig) => { /* use the config with the public API */ },
(rejectReason) => { /* respond to the rejection reason error */ }
);
cfg.parseConfig(path.resolve('./karma.conf.js'), { port: 1337 }).then(
(karmaConfig) => {
/* use the config with the public API */
},
(rejectReason) => {
/* respond to the rejection reason error */
}
)
```


#### `configFilePath` argument

- **Type:** String | `null` | `undefined`
Expand All @@ -321,9 +258,8 @@ by the `cliOptions` argument will be set.

- JavaScript must use CommonJS modules.
- ECMAScript modules are not currently supported by Karma when using
JavaScript.
- Other formats, such as TypeScript, may support ECMAScript modules.

JavaScript.
- Other formats, such as TypeScript, may support ECMAScript modules.

#### `cliOptions` argument

Expand All @@ -338,45 +274,9 @@ will effectively be ignored in the final configuration.
Supports all the same options as the config file and is applied using the same
`config.set()` method.

The expected source of this argument is parsed command line options, but
The expected source of this argument is parsed command line options, but
programatic users may construct this object or leave it out entirely.


#### `parseOptions` argument

- **Type:** Object | `null` | `undefined`
- **Default Value:** `undefined`

`parseOptions` is an object whose properties are configuration options that
allow additional control over parsing and opt-in access to new behaviors or
features.

These options are only related to parsing configuration files and object and are
not related to the configuration of Karma itself.


##### `parseOptions.promiseConfig` option

- **Type:** Boolean
- **Default Value:** `false`

When `parseOptions.promiseConfig === true`, then `parseConfig` will return a
promise instead of a configuration object.

When this option is `true`, then the function exported by the config file may
return a promise. The resolution of that promise indicates that all asynchronous
activity has been completed. Internally, the resolved/fulfilled value is
ignored. As with synchronous usage, all changes to the config object must be
done with the `config.set()` method.

If the function exported by the config file does not return a promise, then
parsing is completed and an immediately fulfilled promise is returned.

Whether the function exported by the config file returns a promise or not, the
promise returned by `parseConfig()` will resolve with a parsed configuration
object, an instance of the `Config` class, as the value.


## `karma.constants`

### `constants.VERSION`
Expand Down
9 changes: 1 addition & 8 deletions lib/cli.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -285,14 +285,7 @@ exports.run = async () => {
if (cmdNeedsConfig) {
let config
try {
config = await cfg.parseConfig(
cliOptions.configFile,
cliOptions,
{
promiseConfig: true,
throwErrors: true
}
)
config = await cfg.parseConfig(cliOptions.configFile, cliOptions)
} catch (karmaConfigException) {
// The reject reason/exception isn't used to log a message since
// parseConfig already calls a configured logger method with an almost
Expand Down
Loading

0 comments on commit 4e3efeb

Please sign in to comment.