Commit b34da43c authored by Mathieu Giraud's avatar Mathieu Giraud

README.md: update documentation

On #36 and on other older things.
parent 0269ff64
Pipeline #616 passed with stages
in 11 seconds
......@@ -117,12 +117,13 @@ The documentation is completed by the files in [demo/](demo/).
The [demo/cal.should](demo/cal.should) example shows
matching on several lines (`l`), counting inside lines (`w`),
ignoring whitespace differences (`b`), expecting a test to fail (`f`),
ignoring whitespace differences (`b`), expecting a test to fail (`f`)
or allowing a test to fail (`a`),
requiring less than or more than a given number of expressions (`<`/`>`).
[demo/commands.should](demo/commands.should) shows that several commands can be used into a same `.should` file.
[demo/commands.should](demo/commands.should) shows that several commands can be used into a same `.should` file. Tests are flushed after each set of commands.
[demo/exit-codes.should](demo/exit-codes.should) shows how to require a particular exit code.
[demo/exit-codes.should](demo/exit-codes.should) shows how to require a particular exit code with `!EXIT_CODE`.
[demo/variables.should](demo/variables.should) shows how to define and use variables.
......@@ -134,9 +135,10 @@ for example to launch tools like `valgrind` on a test set.
**Options and modifiers**
```shell
usage: should [-h] [--cd PATH] [--cd-same] [--launcher CMD] [--extra ARG]
[--mod MODIFIERS] [--var NAME=value] [--log] [--tap] [--xml]
[-v] [-q] [--retry]
usage: should [-h] [--version] [--cd PATH] [--cd-same] [--launcher CMD]
[--extra ARG] [--mod MODIFIERS] [--var NAME=value]
[--timeout TIMEOUT] [--shuffle] [--only-a] [--only-f] [--log]
[--tap] [--xml] [-v] [-q] [--retry]
should-file [should-file ...]
Test command-line applications through .should files
......@@ -146,22 +148,31 @@ positional arguments:
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--cd PATH directory from which to run the test commands
--cd-same run the test commands from the same directory as the .should files
--launcher CMD launcher preceding each command (or replacing $LAUNCHER)
--extra ARG extra argument after the first word of each command (or replacing $EXTRA)
--mod MODIFIERS global modifiers (uppercase letters cancel previous modifiers)
f/F consider that the test should fail
a/A consider that the test is allowed to fail
r/R consider as a regular expression
w/W count all occurrences, even on a same line
i/I ignore case changes
b/B ignore whitespace differences as soon as there is at least one space. Implies 'r'
l/L search on all the output rather than on every line
z/Z keep leading and trailing spaces
> requires that the expression occurs strictly more than the given number
< requires that the expression occurs strictly less than the given number
--var NAME=value variable definition (then use $NAME in .should files)
--timeout TIMEOUT Delay (in seconds) after which the task is stopped (default: 120)
--shuffle shuffle the tests
--retry launch again the last failed or warned tests
filter options:
--only-a launches only 'a' tests
--only-f launches only 'f' tests
output options:
--log stores the output into .log files
--tap outputs .tap files
......@@ -173,12 +184,14 @@ output options:
**Output.**
By default, `should` only writes to the standard output.
The `--log` and the `--tap` options enable to store the actual output of the tested commands
as well as [`.tap` files](https://testanything.org/tap-specification.html).
The `--log`, `--tap` and `--xml` options enable to store the actual output of the tested commands
as well as [`.tap` files](https://testanything.org/tap-specification.html)
and a JUnit `should.xml` file.
**Exit code.**
`should.py` returns `0` when all the tests passed (or have been skipped, or marked as TODO with `f`). A
As soon as one non-TODO test fails, it returns `1`.
`should.py` returns `0` when all the tests passed (or have been skipped, or marked as `failed-with-ALLOW` with `a`). A
As soon as one regular test fails, or as soon as a test marked with `TODO` pass,
`should.py` returns `1`.
### Alternatives
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment