diff --git a/docs/src/test-api/class-fullconfig.md b/docs/src/test-api/class-fullconfig.md new file mode 100644 index 0000000000..767e9aaa43 --- /dev/null +++ b/docs/src/test-api/class-fullconfig.md @@ -0,0 +1,127 @@ +# class: FullConfig +* since: v1.10 +* langs: js + +## property: FullConfig.forbidOnly +* since: v1.10 +- type: ?<[boolean]> + +See [`property: TestConfig.forbidOnly`]. + +## property: FullConfig.fullyParallel +* since: v1.20 +- type: ?<[boolean]> + +See [`property: TestConfig.fullyParallel`]. + +## property: FullConfig.globalSetup +* since: v1.10 +- type: ?<[string]> + +See [`property: TestConfig.globalSetup`]. + +## property: FullConfig.globalTeardown +* since: v1.10 +- type: ?<[string]> + +See [`property: TestConfig.globalTeardown`]. + +## property: FullConfig.globalTimeout +* since: v1.10 +- type: ?<[int]> + +See [`property: TestConfig.globalTimeout`]. + +## property: FullConfig.grep +* since: v1.10 +- type: ?<[RegExp]|[Array]<[RegExp]>> + +See [`property: TestConfig.grep`]. + +## property: FullConfig.grepInvert +* since: v1.10 +- type: ?<[RegExp]|[Array]<[RegExp]>> + +See [`property: TestConfig.grepInvert`]. + +## property: FullConfig.maxFailures +* since: v1.10 +- type: ?<[int]> + +See [`property: TestConfig.maxFailures`]. + +## property: FullConfig.metadata +* since: v1.10 +- type: ?<[Metadata]> + +See [`property: TestConfig.metadata`]. + +## property: FullConfig.preserveOutput +* since: v1.10 +- type: ?<[PreserveOutput]<"always"|"never"|"failures-only">> + +See [`property: TestConfig.preserveOutput`]. + +## property: FullConfig.projects +* since: v1.10 +- type: ?<[Array]<[TestProject]>> + +See [`property: TestConfig.projects`]. + +## property: FullConfig.quiet +* since: v1.10 +- type: ?<[boolean]> + +See [`property: TestConfig.quiet`]. + +## property: FullConfig.reporter +* since: v1.10 +- type: ?<[string]|[Array]<[Object]>|[BuiltInReporter]<"list"|"dot"|"line"|"github"|"json"|"junit"|"null"|"html">> + - `0` <[string]> Reporter name or module or file path + - `1` <[Object]> An object with reporter options if any + +See [`property: TestConfig.reporter`]. + +## property: FullConfig.reportSlowTests +* since: v1.10 +- type: ?<[null]|[Object]> + - `max` <[int]> The maximum number of slow test files to report. Defaults to `5`. + - `threshold` <[float]> Test duration in milliseconds that is considered slow. Defaults to 15 seconds. + +See [`property: TestConfig.reportSlowTests`]. + +## property: FullConfig.shard +* since: v1.10 +- type: ?<[null]|[Object]> + - `total` <[int]> The total number of shards. + - `current` <[int]> The index of the shard to execute, one-based. + +See [`property: TestConfig.shard`]. + +## property: FullConfig.updateSnapshots +* since: v1.10 +- type: ?<[UpdateSnapshots]<"all"|"none"|"missing">> + +See [`property: TestConfig.updateSnapshots`]. + +## property: FullConfig.webServer +* since: v1.10 +- type: ?<[Object]|[Array]<[Object]>> + - `command` <[string]> Shell command to start. For example `npm run start`.. + - `port` ?<[int]> The port that your http server is expected to appear on. It does wait until it accepts connections. Either `port` or `url` should be specified. + - `url` ?<[string]> The url on your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the server is ready to accept connections. Redirects (3xx status codes) are being followed and the new location is checked. Either `port` or `url` should be specified. + - `ignoreHTTPSErrors` ?<[boolean]> Whether to ignore HTTPS errors when fetching the `url`. Defaults to `false`. + - `timeout` ?<[int]> How long to wait for the process to start up and be available in milliseconds. Defaults to 60000. + - `reuseExistingServer` ?<[boolean]> If true, it will re-use an existing server on the `port` or `url` when available. If no server is running on that `port` or `url`, it will run the command to start a new server. If `false`, it will throw if an existing process is listening on the `port` or `url`. This should be commonly set to `!process.env.CI` to allow the local dev server when running tests locally. + - `stdout` ?<["pipe"|"ignore"]> If `"pipe"`, it will pipe the stdout of the command to the process stdout. If `"ignore"`, it will ignore the stdout of the command. Default to `"ignore"`. + - `stderr` ?<["pipe"|"ignore"]> Whether to pipe the stderr of the command to the process stderr or ignore it. Defaults to `"pipe"`. + - `cwd` ?<[string]> Current working directory of the spawned process, defaults to the directory of the configuration file. + - `env` ?<[Object]<[string], [string]>> Environment variables to set for the command, `process.env` by default. + +See [`property: TestConfig.webServer`]. + +## property: FullConfig.workers +* since: v1.10 +- type: ?<[int]|[string]> + +See [`property: TestConfig.workers`]. diff --git a/docs/src/test-reporter-api/class-reporter.md b/docs/src/test-reporter-api/class-reporter.md index 48a5654208..48ed098b7d 100644 --- a/docs/src/test-reporter-api/class-reporter.md +++ b/docs/src/test-reporter-api/class-reporter.md @@ -94,7 +94,7 @@ Called once before running tests. All tests have been already discovered and put ### param: Reporter.onBegin.config * since: v1.10 -- `config` <[TestConfig]> +- `config` <[FullConfig]> Resolved configuration. diff --git a/utils/doclint/generateFullConfigDoc.js b/utils/doclint/generateFullConfigDoc.js new file mode 100644 index 0000000000..ebb2939308 --- /dev/null +++ b/utils/doclint/generateFullConfigDoc.js @@ -0,0 +1,87 @@ +/** + * Copyright (c) Microsoft Corporation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +// @ts-check + +const path = require('path'); +const fs = require('fs'); +const PROJECT_DIR = path.join(__dirname, '..', '..'); +const md = require('../markdown'); + +const allowList = [ + 'forbidOnly', + 'fullyParallel', + 'globalSetup', + 'globalTeardown', + 'globalTimeout', + 'grep', + 'grepInvert', + 'maxFailures', + 'metadata', + 'version', + 'preserveOutput', + 'projects', + 'reporter', + 'reportSlowTests', + 'rootDir', + 'quiet', + 'shard', + 'updateSnapshots', + 'workers', + 'webServer', + 'configFile', +]; +const allowedNames = new Set(allowList); + +const content = fs.readFileSync(path.join(PROJECT_DIR, 'docs/src/test-api/class-testconfig.md')).toString(); + +function propertyNameFromSection(section) { + section = section.split('\n')[0]; + const match = /\.(\w+)/.exec(section); + if (!match) + return null; + return match[1]; +} + +let sections = content.split('\n## '); +sections = sections.filter(section => { + section = section.split('\n')[0]; + const name = propertyNameFromSection(section); + if (!name) + return true; + return allowedNames.has(name); +}); + +// Change class name to FullConfig. +sections = sections.map(section => { + const lines = section.split('\n'); + lines[0] = lines[0].replace('TestConfig', 'FullConfig'); + return lines.join('\n'); +}); + +// Replace description. +sections = sections.map(section => { + const parts = section.split('\n\n'); + section = parts[0]; + const name = propertyNameFromSection(section); + console.log(name) + if (!name) + return `${section}\n`; + return `${section}\n\nSee [\`property: TestConfig.${name}\`].\n`; +}); + +const fullconfig = sections.join('\n## '); +fs.writeFileSync(path.join(PROJECT_DIR, 'docs/src/test-api/class-fullconfig.md'), fullconfig); \ No newline at end of file