Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add script to automatically dump CLI usage into documentation #3589

Merged
merged 1 commit into from
Nov 30, 2018
Merged

add script to automatically dump CLI usage into documentation #3589

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 64 additions & 60 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -779,73 +779,77 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass

## Usage

```console
<!-- usage -->

```plain
plroebuck marked this conversation as resolved.
Show resolved Hide resolved
Usage: mocha [debug] [options] [files]

Options:
-V, --version output the version number
-A, --async-only force all tests to take a callback (async) or return a promise
-c, --colors force enabling of colors
-C, --no-colors force disabling of colors
-G, --growl enable growl notification support
-O, --reporter-options <k=v,k2=v2,...> reporter-specific options
-R, --reporter <name> specify the reporter to use (default: "spec")
-S, --sort sort test files
-b, --bail bail after first test failure
-d, --debug enable node's debugger, synonym for node --debug
-g, --grep <pattern> only run tests matching <pattern>
-f, --fgrep <string> only run tests containing <string>
-gc, --expose-gc expose gc extension
-i, --invert inverts --grep and --fgrep matches
-r, --require <name> require the given module (default: [])
-s, --slow <ms> specify "slow" test threshold in milliseconds (default: 75)
-t, --timeout <ms> specify test timeout threshold in milliseconds (default: 2000)
-u, --ui <name> specify user-interface (bdd|tdd|qunit|exports) (default: "bdd")
-w, --watch watch files in the current working directory for changes
--check-leaks check for global variable leaks
--full-trace display the full stack trace
--compilers <ext>:<module>,... use the given module(s) to compile files (default: [])
--debug-brk enable node's debugger breaking on the first line
--globals <names> allow the given comma-delimited global [names] (default: [])
--es_staging enable all staged features
--harmony<_classes,_generators,...> all node --harmony* flags are available
--preserve-symlinks Instructs the module loader to preserve symbolic links when resolving and caching modules
--icu-data-dir include ICU data
--inline-diffs display actual/expected differences inline within each string
--no-diff do not show a diff on failure
--inspect activate devtools in chrome
--inspect-brk activate devtools in chrome and break on the first line
--interfaces output provided interfaces and exit
--no-deprecation silence deprecation warnings
--exit force shutdown of the event loop after test run: mocha will call process.exit
--no-timeouts disables timeouts, given implicitly with --debug/--inspect
--no-warnings silence all node process warnings
--opts <path> specify opts path (default: "test/mocha.opts")
--perf-basic-prof enable perf linux profiler (basic support)
--napi-modules enable experimental NAPI modules
--prof log statistical profiling information
--log-timer-events Time events including external callbacks
--recursive include sub directories
--reporters output provided reporters and exit
--retries <times> specify number of times to retry a failed test case (default: 0)
--throw-deprecation throw an exception anytime a deprecated function is used
--trace trace function calls
--trace-deprecation show stack traces on deprecations
--trace-warnings show stack traces on node process warnings
--use_strict enforce strict mode
--watch-extensions <ext>,... specify extensions to monitor with --watch (default: ["js"])
--delay wait for async suite definition
--allow-uncaught enable uncaught errors to propagate
--forbid-only causes test marked with only to fail the suite
--forbid-pending causes pending tests and test marked with skip to fail the suite
--file <file> adds file be loaded prior to suite execution (default: [])
--exclude <file> adds file or glob pattern to ignore (default: [])
-h, --help output usage information
-V, --version output the version number
-A, --async-only force all tests to take a callback (async) or return a promise
-c, --colors force enabling of colors
-C, --no-colors force disabling of colors
-G, --growl enable growl notification support
-O, --reporter-options <k=v,k2=v2,...> reporter-specific options
-R, --reporter <name> specify the reporter to use (default: "spec")
-S, --sort sort test files
-b, --bail bail after first test failure
-d, --debug enable node's debugger, synonym for node --debug
-g, --grep <pattern> only run tests matching <pattern>
-f, --fgrep <string> only run tests containing <string>
-gc, --expose-gc expose gc extension
-i, --invert inverts --grep and --fgrep matches
-r, --require <name> require the given module (default: [])
-s, --slow <ms> specify "slow" test threshold in milliseconds (default: 75)
-t, --timeout <ms> specify test timeout threshold in milliseconds (default: 2000)
-u, --ui <name> specify user-interface (bdd|tdd|qunit|exports) (default: "bdd")
-w, --watch watch files in the current working directory for changes
--check-leaks check for global variable leaks
--full-trace display the full stack trace
--compilers <ext>:<module>,... use the given module(s) to compile files (default: [])
--debug-brk enable node's debugger breaking on the first line
--globals <names> allow the given comma-delimited global [names] (default: [])
--es_staging enable all staged features
--harmony<_classes,_generators,...> all node --harmony* flags are available
--preserve-symlinks Instructs the module loader to preserve symbolic links when resolving and caching modules
--icu-data-dir include ICU data
--inline-diffs display actual/expected differences inline within each string
--no-diff do not show a diff on failure
--inspect activate devtools in chrome
--inspect-brk activate devtools in chrome and break on the first line
--interfaces output provided interfaces and exit
--no-deprecation silence deprecation warnings
--exit force shutdown of the event loop after test run: mocha will call process.exit
--no-timeouts disables timeouts, given implicitly with --debug/--inspect
--no-warnings silence all node process warnings
--opts <path> specify opts path (default: "test/mocha.opts")
--perf-basic-prof enable perf linux profiler (basic support)
--napi-modules enable experimental NAPI modules
--prof log statistical profiling information
--log-timer-events Time events including external callbacks
--recursive include sub directories
--reporters output provided reporters and exit
--retries <times> specify number of times to retry a failed test case (default: 0)
--throw-deprecation throw an exception anytime a deprecated function is used
--trace trace function calls
--trace-deprecation show stack traces on deprecations
--trace-warnings show stack traces on node process warnings
--use_strict enforce strict mode
--watch-extensions <ext>,... specify extensions to monitor with --watch (default: ["js"])
--delay wait for async suite definition
--allow-uncaught enable uncaught errors to propagate
--forbid-only causes test marked with only to fail the suite
--forbid-pending causes pending tests and test marked with skip to fail the suite
--file <file> adds file be loaded prior to suite execution (default: [])
--exclude <file> adds file or glob pattern to ignore (default: [])
-h, --help output usage information

Commands:
init <path> initialize a client-side mocha setup at <path>
init <path> initialize a client-side mocha setup at <path>
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why was indentation removed? Running --help on most programs displays cmdline options with indentation.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

probably has to do with the lack of a tty somewhere.

the actual bin/mocha --help output has indents.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's what I thought this was supposed to do -- run mocha --help and paste its exact content.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it does, but the exact content when run without a terminal window doesn't have the leading indents, ostensibly because process.stdout.columns is undefined.

I don't know how to force this value to be present unless I monkeypatch it; it comes out of Node.js internals. it'd need to be monkeypatched for this script only, which is honestly more effort than I'd like to go to... if you can figure out how to fake a tty for this, go ahead and make the necessary changes. I'm curious about the solution, anyway!


<!-- usagestop -->

### `-w, --watch`

Executes tests on changes to JavaScript in the CWD, and once initially.
Expand Down
Loading