From a9cb82b543b59bc682251f551bbac56fbb4e21a4 Mon Sep 17 00:00:00 2001 From: Nicholas Petruzzelli Date: Sun, 13 Feb 2022 14:27:01 -0500 Subject: [PATCH 1/3] docs: document asynchronous configurations in the config file docs --- docs/config/01-configuration-file.md | 42 +++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/config/01-configuration-file.md b/docs/config/01-configuration-file.md index dfa0bf1cd..7535453c1 100644 --- a/docs/config/01-configuration-file.md +++ b/docs/config/01-configuration-file.md @@ -81,6 +81,45 @@ require('ts-node').register({ require('./karma.conf.ts'); ``` +### Asynchronous Configuration + +The function exported by the configuration file may return a promise whose +resolution will tell Karma when all configuration is complete, including the +final call to `config.set()`. + +Just as with a synchronous configuration's return value not being used, an +asynchronous configuration's resolved value will not be used. With both +configuration types, `config.set()` MUST BE called to assign the configuration +object. + +When using the command line interface, returning a promise is all that is +needed. + +An example of a config that may need asynchronous support is a config that uses +an async method to find an available port if the preferred port is already in +use. + +```js +// karma.conf.js +const findAvailablePort = require('./findAvailablePort.js'); + +module.exports = function configKarma(config) { + const myPreferredPort = 9876; + return findAvailablePort(myPreferredPort) + .then(function onFreePortResolved(freePort) { + config.set({ + frameworks: ['jasmine'], + port: freePort, + // ... other Karma configuration + }); + }); +} +``` + +If you are using the `parseConfig` method from the public API, then please see +the [Public API Documentation][dev/public-api]] for details, usage, and +addtional information. + ## File Patterns All of the configuration options, which specify file paths, use the [minimatch][minimatch] library to facilitate flexible but concise file expressions so you can easily list all of the files you want to include and exclude. @@ -526,7 +565,7 @@ The plugin must provide an express/connect middleware function (details about th function CustomMiddlewareFactory (config) { return function (request, response, /* next */) { response.writeHead(200) - return response.end("content!") + return response.end('content!') } } ``` @@ -890,5 +929,6 @@ If you see this error, you can try increasing the socket connection timeout. [config/files]: files.html [config/browsers]: browsers.html [config/preprocessors]: preprocessors.html +[dev/public-api]: ../dev/public-api.html [log4js]: https://github.com/nomiddlename/log4js-node [minimatch]: https://github.com/isaacs/minimatch From 8b89285c7906d397a45791dbeb69f0cdeb5d090d Mon Sep 17 00:00:00 2001 From: Nicholas Petruzzelli Date: Mon, 7 Mar 2022 08:03:56 -0500 Subject: [PATCH 2/3] docs: fix syntax error, make example generic, and simplify docs for async config --- docs/config/01-configuration-file.md | 29 +++++++++++----------------- 1 file changed, 11 insertions(+), 18 deletions(-) diff --git a/docs/config/01-configuration-file.md b/docs/config/01-configuration-file.md index 7535453c1..94976d85d 100644 --- a/docs/config/01-configuration-file.md +++ b/docs/config/01-configuration-file.md @@ -87,37 +87,30 @@ The function exported by the configuration file may return a promise whose resolution will tell Karma when all configuration is complete, including the final call to `config.set()`. -Just as with a synchronous configuration's return value not being used, an -asynchronous configuration's resolved value will not be used. With both -configuration types, `config.set()` MUST BE called to assign the configuration -object. - -When using the command line interface, returning a promise is all that is -needed. - -An example of a config that may need asynchronous support is a config that uses -an async method to find an available port if the preferred port is already in -use. - ```js // karma.conf.js -const findAvailablePort = require('./findAvailablePort.js'); +const getAsyncConfig = require('./getAsyncConfig.js'); module.exports = function configKarma(config) { - const myPreferredPort = 9876; - return findAvailablePort(myPreferredPort) - .then(function onFreePortResolved(freePort) { + return getAsyncConfig() + .then(function onResolved(asyncInfo) { config.set({ + basePath: '../..', frameworks: ['jasmine'], - port: freePort, // ... other Karma configuration + // ... including the use of `asyncInfo` }); }); } ``` +Just as with a synchronous configuration's return value not being used, an +asynchronous configuration's resolved value will not be used. With both +configuration types, `config.set()` MUST BE called to assign the configuration +object. + If you are using the `parseConfig` method from the public API, then please see -the [Public API Documentation][dev/public-api]] for details, usage, and +the [Public API Documentation][dev/public-api] for details, usage, and addtional information. ## File Patterns From 5c710db1b31c2c2178668bd9d06cde259ccd3096 Mon Sep 17 00:00:00 2001 From: Nicholas Petruzzelli Date: Mon, 18 Apr 2022 08:04:07 -0400 Subject: [PATCH 3/3] docs: use async/await in async docs --- docs/config/01-configuration-file.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/config/01-configuration-file.md b/docs/config/01-configuration-file.md index 94976d85d..f839d94e7 100644 --- a/docs/config/01-configuration-file.md +++ b/docs/config/01-configuration-file.md @@ -91,16 +91,14 @@ final call to `config.set()`. // karma.conf.js const getAsyncConfig = require('./getAsyncConfig.js'); -module.exports = function configKarma(config) { - return getAsyncConfig() - .then(function onResolved(asyncInfo) { - config.set({ - basePath: '../..', - frameworks: ['jasmine'], - // ... other Karma configuration - // ... including the use of `asyncInfo` - }); - }); +module.exports = async (config) => { + const asyncInfo = await getAsyncConfig() + config.set({ + basePath: '../..', + frameworks: ['jasmine'], + // ... other Karma configuration + // ... including the use of `asyncInfo` + }); } ```