feat(command): Add --pattern flag for tests (#44)

With the `--pattern` flag available for the `test` and `start` commands, we can filter down which tests are being run. This is particularly useful when running tests in watch mode. This is probably more realistic than running `benmvp start` on the whole source code.

Author: benmvp

docs/api/build.md

@@ -44,7 +44,7 @@ build({
 })
 ```
 
-## Type
+## Signature
 
 `build()` has the following [TypeScript](https://www.typescriptlang.org/) signature:
 

docs/api/start.md

@@ -6,15 +6,15 @@ Looking for CLI docs? View companion [`benmvp start` documentation](../cli/start
 
 ## Examples
 
-To run all modes (default behavior):
+To continuously run all modes on all files (default behavior):
 
 ```js
 import {start} from '@benmvp/cli'
 
 start()
 ```
 
-To run just type-checking:
+To continuously run just type-checking on all files:
 
 ```js
 import {start} from '@benmvp/cli'
@@ -24,7 +24,7 @@ start({
 })
 ```
 
-To run linting & unit tests:
+To continuously run linting & unit tests on all files:
 
 ```sh
 import {start} from '@benmvp/cli'
@@ -34,12 +34,39 @@ start({
 })
 ```
 
-## Type
+To continuously run all modes only on files within `utils/` directories:
+
+```js
+import {test} from '@benmvp/cli'
+
+start({
+  pattern: 'utils/',
+})
+```
+
+To continuously run just linting on files within `api/` directories:
+
+```js
+import {test} from '@benmvp/cli'
+
+start({
+  modes: ['lint'],
+  pattern: 'api/',
+})
+```
+
+## Signature
 
 `start()` has the following [TypeScript](https://www.typescriptlang.org/) signature:
 
 ```js
-([options]: Options): Promise<Result>
+type Mode = 'type' | 'lint' | 'unit'
+namespace TestOptions {
+  modes: Mode[];
+  pattern: string;
+}
+
+([options]: TestOptions): Promise<Result>
 ```
 
 ## Options
@@ -58,6 +85,12 @@ Optional. Defaults to all modes when unspecified.
 
 > NOTE: [Jest Watch Plugins](https://jestjs.io/docs/en/watch-plugins) are added to make watch mode even more useful. Specifically the [eslint `watch-fix` plugin](https://github.com/jest-community/jest-runner-eslint#toggle---fix-in-watch-mode) is added to enable auto-fixing of lint errors. However, for this to work, `'lint'` has to be the first mode when specified.
 
+### `pattern`
+
+A regexp pattern string that is matched against all tests paths before executing the test.
+
+Optional. Defaults to `''` (signifying no filter)
+
 ## Return Value
 
 `start()` returns a `Promise`.

docs/api/test.md

@@ -8,15 +8,15 @@ Looking for CLI docs? View companion [`benmvp test` documentation](../cli/test.m
 
 ## Examples
 
-To run all modes (default behavior):
+To run all modes on all files (default behavior):
 
 ```js
 import {test} from '@benmvp/cli'
 
 test()
 ```
 
-To run just unit tests:
+To run just unit tests on all files:
 
 ```js
 import {test} from '@benmvp/cli'
@@ -26,27 +26,56 @@ test({
 })
 ```
 
-To run typing & linting:
+To run linting & typing on all files:
 
 ```js
 import {test} from '@benmvp/cli'
 
 test({
-  modes: ['type', 'lint'],
+  modes: ['lint', 'type'],
 })
 ```
 
-## Type
+To run all modes only on files within `utils/` directories:
+
+```js
+import {test} from '@benmvp/cli'
+
+test({
+  pattern: 'utils/',
+})
+```
+
+To just run linting on files within `api/` directories while continuously watching for changes:
+
+```js
+import {test} from '@benmvp/cli'
+
+test({
+  modes: ['lint'],
+  pattern: 'api/',
+  watch: true,
+})
+```
+
+## Signature
 
 `test()` has the following [TypeScript](https://www.typescriptlang.org/) signature:
 
 ```js
-([options]: Options): Promise<Result>
+type Mode = 'type' | 'lint' | 'unit'
+namespace TestOptions {
+  modes: Mode[];
+  pattern: string;
+  watch: boolean;
+}
+
+([options]: TestOptions): Promise<Result>
 ```
 
 ## Options
 
-The optional `Options` object supports the following properties:
+The optional `TestOptions` object supports the following properties:
 
 ### `modes`
 
@@ -58,6 +87,12 @@ An `Array` of the types or modes of tests to run. Available modes:
 
 Optional. Defaults to all modes when unspecified. 
 
+### `pattern`
+
+A regexp pattern string that is matched against all tests paths before executing the test.
+
+Optional. Defaults to `''` (signifying no filter)
+
 ### `watch`
 
 A flag indicating whether or not to continuously run the tests whenever source files change.

docs/cli/start.md

@@ -8,24 +8,36 @@ Looking for Node API docs? View companion [`start()` documentation](../api/start
 
 ## Examples
 
-To run all modes (default behavior):
+To continuously run all modes on all files (default behavior):
 
 ```sh
 benmvp start
 ```
 
-To run just type-checking:
+To continuously run just type-checking on all files:
 
 ```sh
 benmvp start --modes type
 ```
 
-To run linting & unit tests:
+To continuously run linting & unit tests on all files:
 
 ```sh
 benmvp start --modes lint unit
 ```
 
+To continuously run all modes only on files within `utils/` directories:
+
+```sh
+benmvp start --pattern utils/
+```
+
+To continuously run just linting on files within `api/` directories:
+
+```sh
+benmvp start --modes lint --pattern api/
+```
+
 ## Arguments
 
 ### `--modes`
@@ -40,6 +52,12 @@ Optional. Defaults to all modes.
 
 > NOTE: [Jest Watch Plugins](https://jestjs.io/docs/en/watch-plugins) are added to make watch mode even more useful. Specifically the [eslint `watch-fix` plugin](https://github.com/jest-community/jest-runner-eslint#toggle---fix-in-watch-mode) is added to enable auto-fixing of lint errors. However, for this to work, `lint` has to be the first mode when specified.
 
+### `--pattern`
+
+A regexp pattern string that is matched against all tests paths before executing the test. Aliased as `-p`.
+
+Optional. Defaults to `''` (signifying no filter)
+
 ---
 
 ## More help

docs/cli/test.md

@@ -8,22 +8,34 @@ Looking for Node API docs? View companion [`test()` documentation](../api/test.m
 
 ## Examples
 
-To run all modes (default behavior):
+To run all modes on all files (default behavior):
 
 ```sh
 benmvp test
 ```
 
-To run just unit tests:
+To run just unit tests on all files:
 
 ```sh
 benmvp test --modes unit
 ```
 
-To run typing & linting:
+To run linting & typing on all files:
 
 ```sh
-benmvp start --modes lint type
+benmvp test --modes lint type
+```
+
+To run all modes only on files within `utils/` directories:
+
+```sh
+benmvp test --patern utils/
+```
+
+To just run linting on files within `api/` directories while continuously watching for changes:
+
+```sh
+benmvp test --modes lint --pattern api/ --watch
 ```
 
 ## Arguments
@@ -38,6 +50,12 @@ A space-separated list of the types or modes of tests to run. Aliased as `-m`. A
 
 Optional. Defaults to all modes.
 
+### `--pattern`
+
+A regexp pattern string that is matched against all tests paths before executing the test. Aliased as `-p`.
+
+Optional. Defaults to `''` (signifying no filter)
+
 ### `--watch`
 
 A flag indicating whether or not to continuously run the tests whenever source files change. Aliased as `-w`.