Skip to content

readme tweaks #57

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

Merged
merged 2 commits into from
Feb 23, 2023
Merged

readme tweaks #57

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
caafab6
readme tweaks
jasonkarns Feb 23, 2023
0beceef
Update README.md
jasonkarns Feb 23, 2023
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
72 changes: 39 additions & 33 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,9 @@ refute_line -- '--'

Fail if the given expression evaluates to false.

***Note:***
*The expression must be a simple command.
[Compound commands][bash-comp-cmd], such as `[[`, can be used only when executed with `bash -c`.*
> _**Note**:
> The expression must be a simple command.
> [Compound commands][bash-comp-cmd], such as `[[`, can be used only when executed with `bash -c`._

```bash
@test 'assert()' {
Expand All @@ -86,9 +86,9 @@ expression : [ 1 -lt 0 ]

Fail if the given expression evaluates to true.

***Note:***
*The expression must be a simple command.
[Compound commands][bash-comp-cmd], such as `[[`, can be used only when executed with `bash -c`.*
> _**Note**
> The expression must be a simple command.
> [Compound commands][bash-comp-cmd], such as `[[`, can be used only when executed with `bash -c`._

```bash
@test 'refute()' {
Expand Down Expand Up @@ -294,7 +294,8 @@ An error is displayed when used simultaneously.
Regular expression matching can be enabled with the `--regexp` option (`-e` for short).
When used, the assertion fails if the *extended regular expression* does not match `$output`.

*Note: The anchors `^` and `$` bind to the beginning and the end of the entire output (not individual lines), respectively.*
> _**Note**:
> The anchors `^` and `$` bind to the beginning and the end of the entire output (not individual lines), respectively._

```bash
@test 'assert_output() regular expression matching' {
Expand Down Expand Up @@ -410,7 +411,8 @@ An error is displayed when used simultaneously.
Regular expression matching can be enabled with the `--regexp` option (`-e` for short).
When used, the assertion fails if the *extended regular expression* matches `$output`.

*Note: The anchors `^` and `$` bind to the beginning and the end of the entire output (not individual lines), respectively.*
> _**Note**:
> The anchors `^` and `$` bind to the beginning and the end of the entire output (not individual lines), respectively._

```bash
@test 'refute_output() regular expression matching' {
Expand Down Expand Up @@ -457,8 +459,9 @@ It checks that the expected line appears in the output (default) or in a specifi
Matching can be literal (default), partial or regular expression.
This function is the logical complement of `refute_line`.

***Warning:***
*Due to a [bug in Bats][bats-93], empty lines are discarded from `${lines[@]}`, causing line indices to change and preventing testing for empty lines.*
> _**Warning**:
> Due to a [bug in Bats][bats-93], empty lines are discarded from `${lines[@]}`,
> causing line indices to change and preventing testing for empty lines._

[bats-93]: https://github.com/sstephenson/bats/pull/93

Expand All @@ -476,9 +479,9 @@ The assertion fails if the expected line is not found in `${lines[@]}`.

On failure, the expected line and the output are displayed.

***Warning:***
*The output displayed does not contain empty lines.
See the Warning above for more.*
> _**Warning**:
> The output displayed does not contain empty lines.
> See the Warning above for more._

```
-- output does not contain line --
Expand Down Expand Up @@ -546,7 +549,8 @@ An error is displayed when used simultaneously.
Regular expression matching can be enabled with the `--regexp` option (`-e` for short).
When used, a match fails if the *extended regular expression* does not match the line being tested.

*Note: As expected, the anchors `^` and `$` bind to the beginning and the end of the matched line, respectively.*
> _**Note**:
> As expected, the anchors `^` and `$` bind to the beginning and the end of the matched line, respectively._

```bash
@test 'assert_line() regular expression matching' {
Expand Down Expand Up @@ -578,8 +582,9 @@ It checks that the unexpected line does not appear in the output (default) or in
Matching can be literal (default), partial or regular expression.
This function is the logical complement of `assert_line`.

***Warning:***
*Due to a [bug in Bats][bats-93], empty lines are discarded from `${lines[@]}`, causing line indices to change and preventing testing for empty lines.*
> _**Warning**:
> Due to a [bug in Bats][bats-93], empty lines are discarded from `${lines[@]}`,
> causing line indices to change and preventing testing for empty lines._

[bats-93]: https://github.com/sstephenson/bats/pull/93

Expand All @@ -597,9 +602,9 @@ The assertion fails if the unexpected line is found in `${lines[@]}`.

On failure, the unexpected line, the index of its first match and the output with the matching line highlighted are displayed.

***Warning:***
*The output displayed does not contain empty lines.
See the Warning above for more.*
> _**Warning**:
> The output displayed does not contain empty lines.
> See the Warning above for more._

```
-- line should not be in output --
Expand Down Expand Up @@ -669,7 +674,8 @@ An error is displayed when used simultaneously.
Regular expression matching can be enabled with the `--regexp` option (`-e` for short).
When used, a match fails if the *extended regular expression* matches the line being tested.

*Note: As expected, the anchors `^` and `$` bind to the beginning and the end of the matched line, respectively.*
> _**Note**:
> As expected, the anchors `^` and `$` bind to the beginning and the end of the matched line, respectively._

```bash
@test 'refute_line() regular expression matching' {
Expand Down Expand Up @@ -723,11 +729,11 @@ format.
An error is displayed if the specified extended regular expression is invalid.

For description of the matching behavior, refer to the documentation of the
`=~` operator in the
[Bash manual]: https://www.gnu.org/software/bash/manual/html_node/Conditional-Constructs.html.
Note that the `BASH_REMATCH` array is available immediately after the
assertion succeeds but is fragile, i.e. prone to being overwritten as a side
effect of other actions.
`=~` operator in the [Bash manual][bash-conditional].

> _**Note**:
> the `BASH_REMATCH` array is available immediately after the assertion succeeds but is fragile;
> i.e. prone to being overwritten as a side effect of other actions._

### `refute_regex`

Expand Down Expand Up @@ -763,20 +769,20 @@ If the value or pattern is longer than one line then it is displayed in
An error is displayed if the specified extended regular expression is invalid.

For description of the matching behavior, refer to the documentation of the
`=~` operator in the
[Bash manual]: https://www.gnu.org/software/bash/manual/html_node/Conditional-Constructs.html.
`=~` operator in the [Bash manual][bash-conditional].

Note that the `BASH_REMATCH` array is available immediately after the assertion
fails but is fragile, i.e. prone to being overwritten as a side effect of other
actions like calling `run`. Thus, it's good practice to avoid using
`BASH_REMATCH` in conjunction with `refute_regex()`. The valuable information
the array contains is the matching part of the value which is printed in the
failing test log, as mentioned above.
> _**Note**:
> the `BASH_REMATCH` array is available immediately after the assertion fails but is fragile;
> i.e. prone to being overwritten as a side effect of other actions like calling `run`.
> Thus, it's good practice to avoid using `BASH_REMATCH` in conjunction with `refute_regex()`.
> The valuable information the array contains is the matching part of the value which is printed in the failing test log, as mentioned above._

<!-- REFERENCES -->

[bats]: https://github.com/bats-core/bats-core
[bash-comp-cmd]: https://www.gnu.org/software/bash/manual/bash.html#Compound-Commands
[bash-conditional]: https://www.gnu.org/software/bash/manual/bash.html#Conditional-Constructs

[bats-docs]: https://bats-core.readthedocs.io/
[bats-support-output]: https://github.com/bats-core/bats-support#output-formatting
[bats-support]: https://github.com/bats-core/bats-support