From 995b916add3a19810d6603274b06267f82d1d454 Mon Sep 17 00:00:00 2001 From: Simon Lydell Date: Wed, 20 Jan 2021 18:35:55 +0100 Subject: [PATCH] Improve readme and --help (#473) - Recommend installing locally. Fixes https://github.com/rtfeldman/node-test-runner/issues/249. - Move more common flags first, both in the readme and in `--help`. - Sync the descriptions between the readme and `--help`. - Try to explain the difference between node-test-runner and elm-explorations/test. - Document where to put your tests. - Various other little tweaks to try to be more helpful. PR for elm-explorations/test: https://github.com/elm-explorations/test/pull/160 We should also update the repo description because it currently says: > Runs elm-test suites from Node.js. Get it with npm install -g elm-test --- CHANGELOG.md | 40 +++------- README.md | 194 +++++++++++++++++++++++++++++++-------------- lib/elm-test.js | 20 ++--- prettier.config.js | 1 + 4 files changed, 158 insertions(+), 97 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a530a568..0d96a8ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,7 @@ Notable changes to this project will be documented in this file. -The format is based on [Keep a Changelog](http://keepachangelog.com/). -This project mirrors major Elm versions. So version 0.18.\* of this project will -be compatible with Elm 0.18.\*. +The format is based on [Keep a Changelog](http://keepachangelog.com/). This project mirrors major Elm versions. So version 0.18.\* of this project will be compatible with Elm 0.18.\*. ## 0.19.1-revision4 - 2020-09-21 @@ -101,8 +99,7 @@ be compatible with Elm 0.18.\*. ### Fixed -- All reporters were considered "machine readable", resulting in the error - stream being ignored (#161) +- All reporters were considered "machine readable", resulting in the error stream being ignored (#161) ### Added @@ -117,8 +114,7 @@ be compatible with Elm 0.18.\*. ### Changed -- Imports in the `Example.elm` file are now sorted for compatibility with - `elm-format@exp` +- Imports in the `Example.elm` file are now sorted for compatibility with `elm-format@exp` ## 0.18.5 - 2017-06-11 @@ -128,8 +124,7 @@ be compatible with Elm 0.18.\*. ### Added -- If your project depends on `elm-lang/html`, `elm-test init` will add a - dependency to `eeue56/elm-html-test` so you can test your HTML. (#154) +- If your project depends on `elm-lang/html`, `elm-test init` will add a dependency to `eeue56/elm-html-test` so you can test your HTML. (#154) ## 0.18.4 - 2017-05-30 @@ -142,21 +137,15 @@ be compatible with Elm 0.18.\*. ### Added -- `--add-dependencies target/elm-package.json` flag to add any missing - dependencies _from_ the `elm-package.json` file in the current director _to_ the - `target/elm-package.json` file. (#28) +- `--add-dependencies target/elm-package.json` flag to add any missing dependencies _from_ the `elm-package.json` file in the current director _to_ the `target/elm-package.json` file. (#28) - `Test.todo` to mark tests as _not yet implemented_. (#104) - `--fuzz` flag to override the default fuzz count. (#77) - `Test.only` and `Test.skip` to limit which tests will be executed. ### Changed -- `elm-test init` now adds all dependencies from the package `elm-package.json` - to the generated `tests/elm-package.json` file. (#68) -- You no longer write a `tests/Main.elm` file. Rather, you pass the paths to - your tests to the `elm-test` executable to run just those files, or you run - `elm-test` without arguments which will look for all elm files under `tests/` - and `test/`. (#72) +- `elm-test init` now adds all dependencies from the package `elm-package.json` to the generated `tests/elm-package.json` file. (#68) +- You no longer write a `tests/Main.elm` file. Rather, you pass the paths to your tests to the `elm-test` executable to run just those files, or you run `elm-test` without arguments which will look for all elm files under `tests/` and `test/`. (#72) - All exposed values of type `Test` are executed by the test-runner. - Duplicate titles/descriptions fail the test run. (#115) - Empty describes are no longer allowed. (#95) @@ -164,19 +153,14 @@ be compatible with Elm 0.18.\*. ### Fixed - Ignores `elm-stuff` (#100) -- Tests that throw a runtime exception fail with the exception message as - failure, rather than crashing the runner. (#69) +- Tests that throw a runtime exception fail with the exception message as failure, rather than crashing the runner. (#69) #### Migrating from `0.18.2` - Upgrade the runner `npm i -g elm-test` - Remove `tests/Main.elm` -- Remove the dependency on `rtfeldman/node-test-runner` from - `tests/elm-package.json` -- Bump the dependency on `elm-community/elm-test` to `4.2.0 <= v < 5.0.0` in - `tests/elm-package.json` -- Ensure your test files expose each test you want to run, and that those values - are of type `Test` -- Make sure those tests aren't defined twice (for example: once as a top-level - value, and again in a `describe` block) or they will be executed twice. +- Remove the dependency on `rtfeldman/node-test-runner` from `tests/elm-package.json` +- Bump the dependency on `elm-community/elm-test` to `4.2.0 <= v < 5.0.0` in `tests/elm-package.json` +- Ensure your test files expose each test you want to run, and that those values are of type `Test` +- Make sure those tests aren't defined twice (for example: once as a top-level value, and again in a `describe` block) or they will be executed twice. - run `elm-test` to execute your tests. diff --git a/README.md b/README.md index 48e23ee0..20db8fe5 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,175 @@ # node-test-runner [![Version](https://img.shields.io/npm/v/elm-test.svg)](https://www.npmjs.com/package/elm-test) -Runs [elm-test](https://package.elm-lang.org/packages/elm-explorations/test/latest) suites from Node.js +Runs [elm-explorations/test] suites in Node.js. + +When people say “elm-test” they usually refer to either: + +- This CLI tool for running tests. +- [elm-explorations/test] – an Elm package for defining tests that this CLI tool can run. + +[elm-explorations/test]: https://package.elm-lang.org/packages/elm-explorations/test/latest ## Installation -```shell -npm install -g elm-test +``` +npm install --save-dev elm-test ``` -## Usage +## Quick start -```shell -elm-test install foo/bar # Install the foo/bar package to "test-dependencies" -elm-test init # `elm-test install elm-explorations/test` and create tests/Example.elm -elm-test # Run all exposed Test values in *.elm files in tests/ -elm-test Foo.elm # Run all exposed Test values in Foo.elm -``` +Install [elm-explorations/test] and create `tests/Example.elm`: -### Command Line Arguments + npx elm-test init -#### `install` +Run tests in the `tests/` folder: -Like `elm install`, except it installs to the `test-dependencies` field of your project's `elm.json` file instead of `dependencies`. + npx elm-test -```shell -elm-test install elm/regex -``` +Run tests in one particular file: -#### `init` + npx elm-test tests/Example.elm -Runs `elm-test install elm-explorations/test` and then creates a `tests/Example.elm` -example test to get you started. +Run tests in files matching a [glob](https://github.com/isaacs/node-glob#glob-primer): -Afterwards, you can run `elm-test` with no arguments to try out the example. + npx elm-test "src/**/*Tests.elm" -#### `--compiler` +> Note: The double quotes are important! Without quotes, your shell might expand the globs for you. With quotes, elm-test expands the globs. This way the watcher can pick up new tests matching the globs, and it will work cross-platform. -The `--compiler` flag can be used to use a version of the Elm compiler that -has not been installed globally. +Run in watch mode: -```shell -npm install elm -elm-test --compiler ./node_modules/.bin/elm -``` + npx elm-test --watch -#### `--seed` +## Where to put tests -Allow running the tests with a predefined seed, rather than a randomly generated seed. This is especially helpful when trying to reproduce a failing fuzz-test. +### Locating files containing tests -```shell -elm-test --seed=12345 -``` +There are 3 places you could put your tests: -#### `--fuzz` +1. In the `tests/` folder. -Define how many times a fuzzer should run. Defaults to `100` + This is the default and requires no extra setup. -```shell -elm-test --fuzz=500 -``` +2. In any source directory (`"source-directories"` in `elm.json` for applications, `src/` for packages) as separate files. -#### `--report` + A convention is to put test files next to the file it tests with a `Tests` suffix. For example, you could have `src/LoginForm.elm` and `src/LoginFormTests.elm`. -Specify which reporter to use for reporting your test results. Valid options are: + This requires telling elm-test which folders/files to run. Examples: -- `console` (default): pretty, human readable formatted output -- `json`: every event will be written to stdout as a json-encoded object -- `junit`: junit-compatible xml will be written to stdout + npx elm-test "src/**/*Tests.elm" + npx elm-test test/frontend/elm -```shell -elm-test --report=json -``` + You might also need to configure your editor to understand that the `"test-dependencies"` in your `elm.json` are available in these files. + +3. In already existing source files. + + This allows testing internal functions without exposing them. (Be aware that testing implementation details can sometimes be counter-productive.) + + This requires moving everything in `"test-dependencies"` in your `elm.json` into regular `"dependencies"`, so your project still compiles. This also helps your editor. Note that this approach isn’t suitable for packages, since you don’t want your package to unnecessarily depend on [elm-explorations/test]. + +You can mix all three variants if you want: -#### `--version` + npx elm-test tests "src/**/*Tests.elm" app -Displays the version of the current elm-test. +> In this example, `"src"` and `"app"` need to be in `"source-directories"` in `elm.json`. -```shell -$ elm-test --version -0.19.1 +### Locating tests within files + +For elm-test to find tests in your files you need to: + +1. Create top-level values of the type [Test](https://package.elm-lang.org/packages/elm-explorations/test/latest/Test#Test). You can name the values anything – the only thing that matters is that their type is `Test`. +2. Expose them. + +Example: + +```elm +module LoginForm exposing (alreadyLoggedInTests, tests) + +import Test exposing (Test) + + +tests : Test +tests = + -- ... + + +alreadyLoggedInTests : Test +alreadyLoggedInTests = + -- ... ``` -#### `--watch` +Some prefer to expose a single `Test` value and group everything using [describe](https://package.elm-lang.org/packages/elm-explorations/test/latest/Test#describe). Some prefer to expose several `Test` values. + +**Also check out the [elm-explorations/test quick-start](https://github.com/elm-explorations/test#quick-start) guide!** + +## Command Line Arguments + +These are the most common commands and flags. Run `elm-test --help` for an exhaustive list. + +**Note:** Throughout this section, the `npx` prefix is omitted for brevity. -Starts the runner in watch mode. Upon changing any currently watched source -files (either in your your source-directories or in your tests' -source-directories), your tests will get rerun. +### install -```shell -elm-test --watch +Like `elm install`, except elm-test will install to `"test-dependencies"` in your `elm.json` instead of to `"dependencies"`. + + elm-test install elm/regex + +### init + +Runs `elm-test install elm-explorations/test` and then creates a `tests/Example.elm` example test to get you started. + +`elm-test init` requires an `elm.json` file up the directory tree, so you will need to run `elm init` first if you don’t already have one. + +After initializing elm-test in your project, try out the example by running `elm-test` with no arguments. + + elm init + elm-test init + elm-test + +### --watch + +Start the runner in watch mode. Your tests will automatically rerun whenever your project changes. + + elm-test --watch + +### --seed + +Run with a specific fuzzer seed, rather than a randomly generated seed. This allows reproducing a failing fuzz-test. The command needed to reproduce (including the `--seed` flag) is printed after each test run. Copy, paste and run it! + + elm-test --seed 336948560956134 + +### --fuzz + +Define how many times each fuzz-test should run. Defaults to `100`. + + elm-test --fuzz 500 + +### --report + +Specify which format to use for reporting test results. Valid options are: + +- `console` (default): pretty, human readable formatted output. +- `json`: newline-delimited json with an object for each event. +- `junit`: junit-compatible xml. + +``` +elm-test --report json ``` -#### `--help` +### --compiler -Displays all the available options and commands. +If `elm` is _not_ in your `$PATH` when elm-test runs, or the Elm executable is called something other than `elm`, you can use this flag to point to your installation. -### Travis CI + elm-test --compiler /path/to/elm + +To run a tool installed locally using `npm` you can use `npx`: + + npx elm-test + +`npx` adds the local `node_modules/.bin/` folder to `$PATH` when it executes the command passed to it. This means that if you have installed `elm` locally, `elm-test` will automatically find that local installation. + +As mentioned in [Installation](#installation) we recommend installing elm-test locally in every project. This ensures all contributors and CI use the same version, to avoid nasty “works on my computer” issues. + +## Travis CI If you want to run your tests on Travis CI, [here's a good starter `.travis.yml`](https://docs.travis-ci.com/user/languages/elm/): @@ -104,3 +178,5 @@ language: elm elm: - 0.19.1 ``` + +Here is an example [`travis.yml`](https://github.com/rtfeldman/elm-css/blob/master/.travis.yml) configuration file for running tests in CI. diff --git a/lib/elm-test.js b/lib/elm-test.js index 44b59c90..7f13a315 100644 --- a/lib/elm-test.js +++ b/lib/elm-test.js @@ -90,41 +90,41 @@ function main() { .name('elm-test') .usage('[options] [globs...]') .description(examples) + .option('--watch', 'Run tests on file changes', false) // For example `--seed` and `--fuzz` only make sense for the “tests” command // and could be specified for that command only, but then they won’t show up // in `--help`. - .option( - '--compiler ', - 'Use a custom path to an Elm executable (default: elm)', - undefined - ) .addOption( - new Option('--seed ', 'Run with a previous fuzzer seed') + new Option('--seed ', 'Run with a specific fuzzer seed') .default(Math.floor(Math.random() * 407199254740991) + 1000, 'random') .argParser(parsePositiveInteger) ) .option( '--fuzz ', - 'Run with each fuzz test performing this many iterations', + 'Define how many times each fuzz-test should run', parsePositiveInteger, 100 ) .addOption( new Option( '--report ', - 'Print results to stdout in the given format' + 'Specify which format to use for reporting test results' ) .default('console') .choices(Report.all) ) - .option('--watch', 'Run tests on file changes', false) + .option( + '--compiler ', + 'Use a custom path to an Elm executable (default: elm)', + undefined + ) .version(packageInfo.version, '--version', 'Print version and exit') .helpOption('-h, --help', 'Show help') .addHelpCommand('help [command]', 'Show help'); program .command('init') - .description('Create example tests') + .description('Install elm-explorations/test and create tests/Example.elm') .action(() => { const options = program.opts(); const pathToElmBinary = getPathToElmBinary(options.compiler); diff --git a/prettier.config.js b/prettier.config.js index c1eb68ae..d48f083b 100644 --- a/prettier.config.js +++ b/prettier.config.js @@ -1,5 +1,6 @@ module.exports = { singleQuote: true, + proseWrap: 'never', overrides: [ { files: '*.js',