{"id":14069562,"url":"https://github.com/bats-core/bats-assert","last_synced_at":"2025-07-30T05:32:31.948Z","repository":{"id":38385583,"uuid":"51543549","full_name":"bats-core/bats-assert","owner":"bats-core","description":"Common assertions for Bats","archived":false,"fork":true,"pushed_at":"2025-06-18T14:46:14.000Z","size":185,"stargazers_count":109,"open_issues_count":23,"forks_count":48,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-08T14:28:46.763Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"ztombol/bats-assert","license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bats-core.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-11T20:11:30.000Z","updated_at":"2025-06-29T12:54:20.000Z","dependencies_parsed_at":"2023-02-09T19:01:25.798Z","dependency_job_id":null,"html_url":"https://github.com/bats-core/bats-assert","commit_stats":null,"previous_names":["jasonkarns/bats-assert-1"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/bats-core/bats-assert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bats-core%2Fbats-assert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bats-core%2Fbats-assert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bats-core%2Fbats-assert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bats-core%2Fbats-assert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bats-core","download_url":"https://codeload.github.com/bats-core/bats-assert/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bats-core%2Fbats-assert/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267815187,"owners_count":24148356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-13T07:07:03.041Z","updated_at":"2025-07-30T05:32:31.940Z","avatar_url":"https://github.com/bats-core.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# bats-assert\n\n[![License](https://img.shields.io/npm/l/bats-assert.svg)](https://github.com/bats-core/bats-assert/blob/master/LICENSE)\n[![GitHub release](https://img.shields.io/github/release/bats-core/bats-assert.svg)](https://github.com/bats-core/bats-assert/releases/latest)\n[![npm release](https://img.shields.io/npm/v/bats-assert.svg)](https://www.npmjs.com/package/bats-assert)\n[![Tests](https://github.com/bats-core/bats-assert/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/bats-core/bats-assert/actions/workflows/test.yml)\n\n`bats-assert` is a helper library providing common assertions for [Bats][bats].\n\n- [Install](#install)\n- [Usage](#usage)\n- [Options](#options)\n- [Full Assertion API](#full-assertion-api)\n\nIn the context of this project, an [assertion][wikipedia-assertions] is a function that perform a test and returns `1` on failure or `0` on success.\nTo make debugging easier, the assertion also outputs relevant information on failure.\nThe output is [formatted][bats-support-output] for readability.\nTo make assertions usable outside of `@test` blocks, the output is sent to [stderr][wikipedia-stderr].\n\nThe most recent invocation of Bats' `run` function is used for testing assertions on output and status code.\n\n[wikipedia-assertions]: https://en.wikipedia.org/wiki/Assertion_(software_development)\n[wikipedia-stderr]: https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)\n\n## Install\n\nThis project has one dependency, for output formatting: [`bats-support`][bats-support]\n\nRead the [shared documentation][bats-docs] to learn how to install and load both libraries.\n\n## Usage\n\nThis project provides the following functions:\n\n - [assert](#assert) / [refute](#refute) Assert a given expression evaluates to `true` or `false`.\n - [assert_equal](#assert_equal) Assert two parameters are equal.\n - [assert_not_equal](#assert_not_equal) Assert two parameters are not equal.\n - [assert_success](#assert_success) / [assert_failure](#assert_failure) Assert exit status is `0` or `1`.\n - [assert_output](#assert_output) / [refute_output](#refute_output) Assert output does (or does not) contain given content.\n - [assert_line](#assert_line) / [refute_line](#refute_line) Assert a specific line of output does (or does not) contain given content.\n - [assert_regex](#assert_regex) / [refute_regex](#refute_regex) Assert a parameter does (or does not) match given pattern.\n - [assert_stderr](#assert_stderr) / [refute_stderr](#refute_stderr) Assert stderr does (or does not) contain given content.\n - [assert_stderr_line](#assert_stderr_line) / [refute_stderr_line](#refute_stderr_line) Assert a specific line of stderr does (or does not) contain given content.\n\nThese commands are described in more detail below.\n\n## Options\n\nFor functions that have options, `--` disables option parsing for the remaining arguments to allow using arguments identical to one of the allowed options.\n\n```bash\nassert_output -- '-p'\n```\n\nSpecifying `--` as an argument is similarly simple.\n\n```bash\nrefute_line -- '--'\n```\n\n\n## Full Assertion API\n\n### `assert`\n\nFail if the given expression evaluates to false.\n\n\u003e _**Note**:\n\u003e The expression must be a simple command.\n\u003e [Compound commands][bash-comp-cmd], such as `[[`, can be used only when executed with `bash -c`._\n\n```bash\n@test 'assert()' {\n  assert [ 1 -lt 0 ]\n}\n```\n\nOn failure, the failed expression is displayed.\n\n```\n-- assertion failed --\nexpression : [ 1 -lt 0 ]\n--\n```\n\n\n### `refute`\n\nFail if the given expression evaluates to true.\n\n\u003e _**Note**\n\u003e The expression must be a simple command.\n\u003e [Compound commands][bash-comp-cmd], such as `[[`, can be used only when executed with `bash -c`._\n\n```bash\n@test 'refute()' {\n  refute [ 1 -gt 0 ]\n}\n```\n\nOn failure, the successful expression is displayed.\n\n```\n-- assertion succeeded, but it was expected to fail --\nexpression : [ 1 -gt 0 ]\n--\n```\n\n\n### `assert_equal`\n\nFail if the two parameters, actual and expected value respectively, do not equal.\n\n```bash\n@test 'assert_equal()' {\n  assert_equal 'have' 'want'\n}\n```\n\nOn failure, the expected and actual values are displayed.\n\n```\n-- values do not equal --\nexpected : want\nactual   : have\n--\n```\n\nIf either value is longer than one line both are displayed in *multi-line* format.\n\n\n### `assert_not_equal`\n\nFail if the two parameters, actual and unexpected value respectively, are equal.\n\n```bash\n@test 'assert_not_equal()' {\n  assert_not_equal 'foobar' 'foobar'\n}\n```\n\nOn failure, the expected and actual values are displayed.\n\n```\n-- values should not be equal --\nunexpected : foobar\nactual     : foobar\n--\n```\n\nIf either value is longer than one line both are displayed in *multi-line* format.\n\n\n### `assert_success`\n\nFail if `$status` is not 0.\n\n```bash\n@test 'assert_success() status only' {\n  run bash -c \"echo 'Error!'; exit 1\"\n  assert_success\n}\n```\n\nOn failure, `$status` and `$output` are displayed.\n\n```\n-- command failed --\nstatus : 1\noutput : Error!\n--\n```\n\nIf `$output` is longer than one line, it is displayed in *multi-line* format.\n\n\n### `assert_failure`\n\nFail if `$status` is 0.\n\n```bash\n@test 'assert_failure() status only' {\n  run echo 'Success!'\n  assert_failure\n}\n```\n\nOn failure, `$output` is displayed.\n\n```\n-- command succeeded, but it was expected to fail --\noutput : Success!\n--\n```\n\nIf `$output` is longer than one line, it is displayed in *multi-line* format.\n\n#### Expected status\n\nWhen one parameter is specified, fail if `$status` does not equal the expected status specified by the parameter.\n\n```bash\n@test 'assert_failure() with expected status' {\n  run bash -c \"echo 'Error!'; exit 1\"\n  assert_failure 2\n}\n```\n\nOn failure, the expected and actual status, and `$output` are displayed.\n\n```\n-- command failed as expected, but status differs --\nexpected : 2\nactual   : 1\noutput   : Error!\n--\n```\n\nIf `$output` is longer than one line, it is displayed in *multi-line* format.\n\n\n### `assert_output`\n\nThis function helps to verify that a command or function produces the correct output by checking that the specified expected output matches the actual output.\nMatching can be literal (default), partial or regular expression.\nThis function is the logical complement of `refute_output`.\n\n#### Literal matching\n\nBy default, literal matching is performed.\nThe assertion fails if `$output` does not equal the expected output.\n\n```bash\n@test 'assert_output()' {\n  run echo 'have'\n  assert_output 'want'\n}\n```\n\nOn failure, the expected and actual output are displayed.\n\n```\n-- output differs --\nexpected : want\nactual   : have\n--\n```\n\nIf either value is longer than one line both are displayed in *multi-line* format.\n\n#### Existence\n\nTo assert that any (non-empty) output exists at all, simply omit the matching argument.\n\n```bash\n@test 'assert_output()' {\n  run echo 'have'\n  assert_output\n}\n```\n\nOn failure, an error message is displayed.\n\n```\n-- no output --\nexpected non-empty output, but output was empty\n--\n```\n\n#### Partial matching\n\nPartial matching can be enabled with the `--partial` option (`-p` for short).\nWhen used, the assertion fails if the expected *substring* is not found in `$output`.\n\n```bash\n@test 'assert_output() partial matching' {\n  run echo 'ERROR: no such file or directory'\n  assert_output --partial 'SUCCESS'\n}\n```\n\nOn failure, the substring and the output are displayed.\n\n```\n-- output does not contain substring --\nsubstring : SUCCESS\noutput    : ERROR: no such file or directory\n--\n```\n\nThis option and regular expression matching (`--regexp` or `-e`) are mutually exclusive.\nAn error is displayed when used simultaneously.\n\n#### Regular expression matching\n\nRegular expression matching can be enabled with the `--regexp` option (`-e` for short).\nWhen used, the assertion fails if the *[extended regular expression]* does not match `$output`.\n\n[extended regular expression]: https://en.wikibooks.org/wiki/Regular_Expressions/POSIX-Extended_Regular_Expressions\n\n\u003e [!IMPORTANT]  \n\u003e Bash [doesn't support](https://stackoverflow.com/a/48898886/5432315) certain parts of regular expressions you may be used to:\n\u003e  * `\\d` `\\D` `\\s` `\\S` `\\w` `\\W` — these can be replaced with POSIX character class equivalents `[[:digit:]]`, `[^[:digit:]]`, `[[:space:]]`, `[^[:space:]]`, `[_[:alnum:]]`, and `[^_[:alnum:]]`, respectively.  (Notice the last case, where the `[:alnum:]` POSIX character class is augmented with underscore to be exactly equivalent to the Perl `\\w` shorthand.)\n\u003e  * Non-greedy matching. You can sometimes replace `a.*?b` with something like `a[^ab]*b` to get a similar effect in practice, though the two are not exactly equivalent.\n\u003e  * Non-capturing parentheses `(?:...)`. In the trivial case, just use capturing parentheses `(...)` instead; though of course, if you use capture groups and/or backreferences, this will renumber your capture groups.\n\u003e  * Lookarounds like `(?\u003c=before)` or `(?!after)`. (In fact anything with `(?` is a Perl extension.)  There is no simple general workaround for these, though you can sometimes rephrase your problem into one where lookarounds can be avoided.\n\n\u003e _**Note**:\n\u003e The anchors `^` and `$` bind to the beginning and the end of the entire output (not individual lines), respectively._\n\n```bash\n@test 'assert_output() regular expression matching' {\n  run echo 'Foobar 0.1.0'\n  assert_output --regexp '^Foobar v[0-9]+\\.[0-9]+\\.[0-9]$'\n}\n```\n\nOn failure, the regular expression and the output are displayed.\n\n```\n-- regular expression does not match output --\nregexp : ^Foobar v[0-9]+\\.[0-9]+\\.[0-9]$\noutput : Foobar 0.1.0\n--\n```\n\nAn error is displayed if the specified extended regular expression is invalid.\n\nThis option and partial matching (`--partial` or `-p`) are mutually exclusive.\nAn error is displayed when used simultaneously.\n\n#### Standard Input, HereDocs and HereStrings\n\nThe expected output can be specified via standard input (also heredoc/herestring) with the `-`/`--stdin` option.\n\n```bash\n@test 'assert_output() with pipe' {\n  run echo 'hello'\n  echo 'hello' | assert_output -\n}\n\n@test 'assert_output() with herestring' {\n  run echo 'hello'\n  assert_output - \u003c\u003c\u003c hello\n}\n```\n\n\n### `refute_output`\n\nThis function helps to verify that a command or function produces the correct output by checking that the specified unexpected output does not match the actual output.\nMatching can be literal (default), partial or regular expression.\nThis function is the logical complement of `assert_output`.\n\n#### Literal matching\n\nBy default, literal matching is performed.\nThe assertion fails if `$output` equals the unexpected output.\n\n```bash\n@test 'refute_output()' {\n  run echo 'want'\n  refute_output 'want'\n}\n```\n\nOn failure, the output is displayed.\n\n```\n-- output equals, but it was expected to differ --\noutput : want\n--\n```\n\nIf output is longer than one line it is displayed in *multi-line* format.\n\n#### Existence\n\nTo assert that there is no output at all, simply omit the matching argument.\n\n```bash\n@test 'refute_output()' {\n  run foo --silent\n  refute_output\n}\n```\n\nOn failure, an error message is displayed.\n\n```\n-- unexpected output --\nexpected no output, but output was non-empty\n--\n```\n\n#### Partial matching\n\nPartial matching can be enabled with the `--partial` option (`-p` for short).\nWhen used, the assertion fails if the unexpected *substring* is found in `$output`.\n\n```bash\n@test 'refute_output() partial matching' {\n  run echo 'ERROR: no such file or directory'\n  refute_output --partial 'ERROR'\n}\n```\n\nOn failure, the substring and the output are displayed.\n\n```\n-- output should not contain substring --\nsubstring : ERROR\noutput    : ERROR: no such file or directory\n--\n```\n\nThis option and regular expression matching (`--regexp` or `-e`) are mutually exclusive.\nAn error is displayed when used simultaneously.\n\n#### Regular expression matching\n\nRegular expression matching can be enabled with the `--regexp` option (`-e` for short).\nWhen used, the assertion fails if the *extended regular expression* matches `$output`.\n\n\u003e _**Note**:\n\u003e The anchors `^` and `$` bind to the beginning and the end of the entire output (not individual lines), respectively._\n\n```bash\n@test 'refute_output() regular expression matching' {\n  run echo 'Foobar v0.1.0'\n  refute_output --regexp '^Foobar v[0-9]+\\.[0-9]+\\.[0-9]$'\n}\n```\n\nOn failure, the regular expression and the output are displayed.\n\n```\n-- regular expression should not match output --\nregexp : ^Foobar v[0-9]+\\.[0-9]+\\.[0-9]$\noutput : Foobar v0.1.0\n--\n```\n\nAn error is displayed if the specified extended regular expression is invalid.\n\nThis option and partial matching (`--partial` or `-p`) are mutually exclusive.\nAn error is displayed when used simultaneously.\n\n#### Standard Input, HereDocs and HereStrings\n\nThe unexpected output can be specified via standard input (also heredoc/herestring) with the `-`/`--stdin` option.\n\n```bash\n@test 'refute_output() with pipe' {\n  run echo 'hello'\n  echo 'world' | refute_output -\n}\n\n@test 'refute_output() with herestring' {\n  run echo 'hello'\n  refute_output - \u003c\u003c\u003c world\n}\n```\n\n\n### `assert_line`\n\nSimilarly to `assert_output`, this function helps to verify that a command or function produces the correct output.\nIt checks that the expected line appears in the output (default) or in a specific line of it.\nMatching can be literal (default), partial or regular expression.\nThis function is the logical complement of `refute_line`.\n\n\u003e _**Warning**:\n\u003e Due to a [bug in Bats][bats-93], empty lines are discarded from `${lines[@]}`,\n\u003e causing line indices to change and preventing testing for empty lines._\n\n[bats-93]: https://github.com/sstephenson/bats/pull/93\n\n#### Looking for a line in the output\n\nBy default, the entire output is searched for the expected line.\nThe assertion fails if the expected line is not found in `${lines[@]}`.\n\n```bash\n@test 'assert_line() looking for line' {\n  run echo $'have-0\\nhave-1\\nhave-2'\n  assert_line 'want'\n}\n```\n\nOn failure, the expected line and the output are displayed.\n\n\u003e _**Warning**:\n\u003e The output displayed does not contain empty lines.\n\u003e See the Warning above for more._\n\n```\n-- output does not contain line --\nline : want\noutput (3 lines):\n  have-0\n  have-1\n  have-2\n--\n```\n\nIf output is not longer than one line, it is displayed in *two-column* format.\n\n#### Matching a specific line\n\nWhen the `--index \u003cidx\u003e` option is used (`-n \u003cidx\u003e` for short), the expected line is matched only against the line identified by the given index.\nThe assertion fails if the expected line does not equal `${lines[\u003cidx\u003e]}`.\n\n```bash\n@test 'assert_line() specific line' {\n  run echo $'have-0\\nhave-1\\nhave-2'\n  assert_line --index 1 'want-1'\n}\n```\n\nOn failure, the index and the compared lines are displayed.\n\n```\n-- line differs --\nindex    : 1\nexpected : want-1\nactual   : have-1\n--\n```\n\n#### Partial matching\n\nPartial matching can be enabled with the `--partial` option (`-p` for short).\nWhen used, a match fails if the expected *substring* is not found in the matched line.\n\n```bash\n@test 'assert_line() partial matching' {\n  run echo $'have 1\\nhave 2\\nhave 3'\n  assert_line --partial 'want'\n}\n```\n\nOn failure, the same details are displayed as for literal matching, except that the substring replaces the expected line.\n\n```\n-- no output line contains substring --\nsubstring : want\noutput (3 lines):\n  have 1\n  have 2\n  have 3\n--\n```\n\nThis option and regular expression matching (`--regexp` or `-e`) are mutually exclusive.\nAn error is displayed when used simultaneously.\n\n#### Regular expression matching\n\nRegular expression matching can be enabled with the `--regexp` option (`-e` for short).\nWhen used, a match fails if the *extended regular expression* does not match the line being tested.\n\n\u003e _**Note**: \n\u003e As expected, the anchors `^` and `$` bind to the beginning and the end of the matched line, respectively._\n\n```bash\n@test 'assert_line() regular expression matching' {\n  run echo $'have-0\\nhave-1\\nhave-2'\n  assert_line --index 1 --regexp '^want-[0-9]$'\n}\n```\n\nOn failure, the same details are displayed as for literal matching, except that the regular expression replaces the expected line.\n\n```\n-- regular expression does not match line --\nindex  : 1\nregexp : ^want-[0-9]$\nline   : have-1\n--\n```\n\nAn error is displayed if the specified extended regular expression is invalid.\n\nThis option and partial matching (`--partial` or `-p`) are mutually exclusive.\nAn error is displayed when used simultaneously.\n\n\n### `refute_line`\n\nSimilarly to `refute_output`, this function helps to verify that a command or function produces the correct output.\nIt checks that the unexpected line does not appear in the output (default) or in a specific line of it.\nMatching can be literal (default), partial or regular expression.\nThis function is the logical complement of `assert_line`.\n\n\u003e _**Warning**:\n\u003e Due to a [bug in Bats][bats-93], empty lines are discarded from `${lines[@]}`, \n\u003e causing line indices to change and preventing testing for empty lines._\n\n[bats-93]: https://github.com/sstephenson/bats/pull/93\n\n#### Looking for a line in the output\n\nBy default, the entire output is searched for the unexpected line.\nThe assertion fails if the unexpected line is found in `${lines[@]}`.\n\n```bash\n@test 'refute_line() looking for line' {\n  run echo $'have-0\\nwant\\nhave-2'\n  refute_line 'want'\n}\n```\n\nOn failure, the unexpected line, the index of its first match and the output with the matching line highlighted are displayed.\n\n\u003e _**Warning**:\n\u003e The output displayed does not contain empty lines.\n\u003e See the Warning above for more._\n\n```\n-- line should not be in output --\nline  : want\nindex : 1\noutput (3 lines):\n  have-0\n\u003e want\n  have-2\n--\n```\n\nIf output is not longer than one line, it is displayed in *two-column* format.\n\n#### Matching a specific line\n\nWhen the `--index \u003cidx\u003e` option is used (`-n \u003cidx\u003e` for short), the unexpected line is matched only against the line identified by the given index.\nThe assertion fails if the unexpected line equals `${lines[\u003cidx\u003e]}`.\n\n```bash\n@test 'refute_line() specific line' {\n  run echo $'have-0\\nwant-1\\nhave-2'\n  refute_line --index 1 'want-1'\n}\n```\n\nOn failure, the index and the unexpected line are displayed.\n\n```\n-- line should differ --\nindex : 1\nline  : want-1\n--\n```\n\n#### Partial matching\n\nPartial matching can be enabled with the `--partial` option (`-p` for short).\nWhen used, a match fails if the unexpected *substring* is found in the matched line.\n\n```bash\n@test 'refute_line() partial matching' {\n  run echo $'have 1\\nwant 2\\nhave 3'\n  refute_line --partial 'want'\n}\n```\n\nOn failure, in addition to the details of literal matching, the substring is also displayed.\nWhen used with `--index \u003cidx\u003e` the substring replaces the unexpected line.\n\n```\n-- no line should contain substring --\nsubstring : want\nindex     : 1\noutput (3 lines):\n  have 1\n\u003e want 2\n  have 3\n--\n```\n\nThis option and regular expression matching (`--regexp` or `-e`) are mutually exclusive.\nAn error is displayed when used simultaneously.\n\n#### Regular expression matching\n\nRegular expression matching can be enabled with the `--regexp` option (`-e` for short).\nWhen used, a match fails if the *extended regular expression* matches the line being tested.\n\n\u003e _**Note**:\n\u003e As expected, the anchors `^` and `$` bind to the beginning and the end of the matched line, respectively._\n\n```bash\n@test 'refute_line() regular expression matching' {\n  run echo $'Foobar v0.1.0\\nRelease date: 2015-11-29'\n  refute_line --index 0 --regexp '^Foobar v[0-9]+\\.[0-9]+\\.[0-9]$'\n}\n```\n\nOn failure, in addition to the details of literal matching, the regular expression is also displayed.\nWhen used with `--index \u003cidx\u003e` the regular expression replaces the unexpected line.\n\n```\n-- regular expression should not match line --\nindex  : 0\nregexp : ^Foobar v[0-9]+\\.[0-9]+\\.[0-9]$\nline   : Foobar v0.1.0\n--\n```\n\nAn error is displayed if the specified extended regular expression is invalid.\n\nThis option and partial matching (`--partial` or `-p`) are mutually exclusive.\nAn error is displayed when used simultaneously.\n\n### `assert_regex`\n\nThis function is similar to `assert_equal` but uses pattern matching instead of\nequality, by wrapping `[[ value =~ pattern ]]`.\n\nFail if the value (first parameter) does not match the pattern (second\nparameter).\n\n```bash\n@test 'assert_regex()' {\n  assert_regex 'what' 'x$'\n}\n```\n\nOn failure, the value and the pattern are displayed.\n\n```\n-- values does not match regular expression --\nvalue    : what\npattern  : x$\n--\n```\n\nIf the value is longer than one line then it is displayed in *multi-line*\nformat.\n\nAn error is displayed if the specified extended regular expression is invalid.\n\nFor description of the matching behavior, refer to the documentation of the\n`=~` operator in the [Bash manual][bash-conditional].\n\n\u003e _**Note**:\n\u003e the `BASH_REMATCH` array is available immediately after the assertion succeeds but is fragile;\n\u003e i.e. prone to being overwritten as a side effect of other actions._\n\n### `refute_regex`\n\nThis function is similar to `refute_equal` but uses pattern matching instead of\nequality, by wrapping `! [[ value =~ pattern ]]`.\n\nFail if the value (first parameter) matches the pattern (second parameter).\n\n```bash\n@test 'refute_regex()' {\n  refute_regex 'WhatsApp' 'Threema'\n}\n```\n\nOn failure, the value, the pattern and the match are displayed.\n\n```bash\n@test 'refute_regex()' {\n  refute_regex 'WhatsApp' 'What.'\n}\n\n-- value matches regular expression --\nvalue    : WhatsApp\npattern  : What.\nmatch    : Whats\ncase     : sensitive\n--\n```\n\nIf the value or pattern is longer than one line then it is displayed in\n*multi-line* format.\n\nAn error is displayed if the specified extended regular expression is invalid.\n\nFor description of the matching behavior, refer to the documentation of the\n`=~` operator in the [Bash manual][bash-conditional].\n\n\u003e _**Note**:\n\u003e the `BASH_REMATCH` array is available immediately after the assertion fails but is fragile;\n\u003e i.e. prone to being overwritten as a side effect of other actions like calling `run`.\n\u003e Thus, it's good practice to avoid using `BASH_REMATCH` in conjunction with `refute_regex()`.\n\u003e The valuable information the array contains is the matching part of the value which is printed in the failing test log, as mentioned above._\n\n### `assert_stderr`\n\n\u003e _**Note**:\n\u003e `run` has to be called with `--separate-stderr` to separate stdout and stderr into `$output` and `$stderr`.\n\u003e If not, `$stderr` will be empty, causing `assert_stderr` to always fail.\n\nSimilarly to `assert_output`, this function verifies that a command or function produces the expected stderr.\nThe stderr matching can be literal (the default), partial or by regular expression.\nThe expected stderr can be specified either by positional argument or read from STDIN by passing the `-`/`--stdin` flag.\n\n#### Literal matching\n\nBy default, literal matching is performed.\nThe assertion fails if `$stderr` does not equal the expected stderr.\n\n  ```bash\n  echo_err() {\n    echo \"$@\" \u003e\u00262\n  }\n\n  @test 'assert_stderr()' {\n    run --separate-stderr echo_err 'have'\n    assert_stderr 'want'\n  }\n\n  @test 'assert_stderr() with pipe' {\n    run --separate-stderr echo_err 'hello'\n    echo_err 'hello' | assert_stderr -\n  }\n\n  @test 'assert_stderr() with herestring' {\n    run --separate-stderr echo_err 'hello'\n    assert_stderr - \u003c\u003c\u003c hello\n  }\n  ```\n\nOn failure, the expected and actual stderr are displayed.\n\n  ```\n  -- stderr differs --\n  expected : want\n  actual   : have\n  --\n  ```\n\n#### Existence\n\nTo assert that any stderr exists at all, omit the `expected` argument.\n\n  ```bash\n  @test 'assert_stderr()' {\n    run --separate-stderr echo_err 'have'\n    assert_stderr\n  }\n  ```\n\nOn failure, an error message is displayed.\n\n  ```\n  -- no stderr --\n  expected non-empty stderr, but stderr was empty\n  --\n  ```\n\n#### Partial matching\n\nPartial matching can be enabled with the `--partial` option (`-p` for short).\nWhen used, the assertion fails if the expected _substring_ is not found in `$stderr`.\n\n  ```bash\n  @test 'assert_stderr() partial matching' {\n    run --separate-stderr echo_err 'ERROR: no such file or directory'\n    assert_stderr --partial 'SUCCESS'\n  }\n  ```\n\nOn failure, the substring and the stderr are displayed.\n\n  ```\n  -- stderr does not contain substring --\n  substring : SUCCESS\n  stderr    : ERROR: no such file or directory\n  --\n  ```\n\n#### Regular expression matching\n\nRegular expression matching can be enabled with the `--regexp` option (`-e` for short).\nWhen used, the assertion fails if the *extended regular expression* does not match `$stderr`.\n\n*Note: The anchors `^` and `$` bind to the beginning and the end (respectively) of the entire stderr; not individual lines.*\n\n  ```bash\n  @test 'assert_stderr() regular expression matching' {\n    run --separate-stderr echo_err 'Foobar 0.1.0'\n    assert_stderr --regexp '^Foobar v[0-9]+\\.[0-9]+\\.[0-9]$'\n  }\n  ```\n\nOn failure, the regular expression and the stderr are displayed.\n\n  ```\n  -- regular expression does not match stderr --\n  regexp : ^Foobar v[0-9]+\\.[0-9]+\\.[0-9]$\n  stderr : Foobar 0.1.0\n  --\n  ```\n\n### `refute_stderr`\n\n\u003e _**Note**:\n\u003e `run` has to be called with `--separate-stderr` to separate stdout and stderr into `$output` and `$stderr`.\n\u003e If not, `$stderr` will be empty, causing `refute_stderr` to always pass.\n\nSimilar to `refute_output`, this function verifies that a command or function does not produce the unexpected stderr.\n(It is the logical complement of `assert_stderr`.)\nThe stderr matching can be literal (the default), partial or by regular expression.\nThe unexpected stderr can be specified either by positional argument or read from STDIN by passing the `-`/`--stdin` flag.\n\n### `assert_stderr_line`\n\n\u003e _**Note**:\n\u003e `run` has to be called with `--separate-stderr` to separate stdout and stderr into `$output` and `$stderr`.\n\u003e If not, `$stderr` will be empty, causing `assert_stderr_line` to always fail.\n\nSimilarly to `assert_stderr`, this function verifies that a command or function produces the expected stderr.\nIt checks that the expected line appears in the stderr (default) or at a specific line number.\nMatching can be literal (default), partial or regular expression.\nThis function is the logical complement of `refute_stderr_line`.\n\n#### Looking for a line in the stderr\n\nBy default, the entire stderr is searched for the expected line.\nThe assertion fails if the expected line is not found in `${stderr_lines[@]}`.\n\n  ```bash\n  echo_err() {\n    echo \"$@\" \u003e\u00262\n  }\n\n  @test 'assert_stderr_line() looking for line' {\n    run --separate-stderr echo_err $'have-0\\nhave-1\\nhave-2'\n    assert_stderr_line 'want'\n  }\n  ```\n\nOn failure, the expected line and the stderr are displayed.\n\n  ```\n  -- stderr does not contain line --\n  line : want\n  stderr (3 lines):\n    have-0\n    have-1\n  have-2\n  --\n  ```\n\n#### Matching a specific line\n\nWhen the `--index \u003cidx\u003e` option is used (`-n \u003cidx\u003e` for short), the expected line is matched only against the line identified by the given index.\nThe assertion fails if the expected line does not equal `${stderr_lines[\u003cidx\u003e]}`.\n\n  ```bash\n  @test 'assert_stderr_line() specific line' {\n    run --separate-stderr echo_err $'have-0\\nhave-1\\nhave-2'\n    assert_stderr_line --index 1 'want-1'\n  }\n  ```\n\nOn failure, the index and the compared stderr_lines are displayed.\n\n  ```\n  -- line differs --\n  index    : 1\n  expected : want-1\n  actual   : have-1\n  --\n  ```\n\n#### Partial matching\n\nPartial matching can be enabled with the `--partial` option (`-p` for short).\nWhen used, a match fails if the expected *substring* is not found in the matched line.\n\n  ```bash\n  @test 'assert_stderr_line() partial matching' {\n    run --separate-stderr echo_err $'have 1\\nhave 2\\nhave 3'\n    assert_stderr_line --partial 'want'\n  }\n  ```\n\nOn failure, the same details are displayed as for literal matching, except that the substring replaces the expected line.\n\n  ```\n  -- no stderr line contains substring --\n  substring : want\n  stderr (3 lines):\n    have 1\n    have 2\n    have 3\n  --\n  ```\n\n#### Regular expression matching\n\nRegular expression matching can be enabled with the `--regexp` option (`-e` for short).\nWhen used, a match fails if the *extended regular expression* does not match the line being tested.\n\n*Note: As expected, the anchors `^` and `$` bind to the beginning and the end (respectively) of the matched line.*\n\n  ```bash\n  @test 'assert_stderr_line() regular expression matching' {\n    run --separate-stderr echo_err $'have-0\\nhave-1\\nhave-2'\n    assert_stderr_line --index 1 --regexp '^want-[0-9]$'\n  }\n  ```\n\nOn failure, the same details are displayed as for literal matching, except that the regular expression replaces the expected line.\n\n  ```\n  -- regular expression does not match line --\n  index  : 1\n  regexp : ^want-[0-9]$\n  line   : have-1\n  --\n  ```\n\n### `refute_stderr_line`\n\n\u003e _**Note**:\n\u003e `run` has to be called with `--separate-stderr` to separate stdout and stderr into `$output` and `$stderr`.\n\u003e If not, `$stderr` will be empty, causing `refute_stderr_line` to always pass.\n\nSimilarly to `refute_stderr`, this function helps to verify that a command or function produces the correct stderr.\nIt checks that the unexpected line does not appear in the stderr (default) or in a specific line of it.\nMatching can be literal (default), partial or regular expression.\nThis function is the logical complement of `assert_stderr_line`.\n\n\u003c!-- REFERENCES --\u003e\n\n[bats]: https://github.com/bats-core/bats-core\n[bash-comp-cmd]: https://www.gnu.org/software/bash/manual/bash.html#Compound-Commands\n[bash-conditional]: https://www.gnu.org/software/bash/manual/bash.html#Conditional-Constructs\n\n[bats-docs]: https://bats-core.readthedocs.io/\n[bats-support-output]: https://github.com/bats-core/bats-support#output-formatting\n[bats-support]: https://github.com/bats-core/bats-support\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbats-core%2Fbats-assert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbats-core%2Fbats-assert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbats-core%2Fbats-assert/lists"}