1 files changed, 44 insertions, 0 deletions
diff --git a/README.md b/README.md
index 4544538..c662ab8 100644
--- a/README.md
+++ b/README.md
@@ -728,6 +728,50 @@ 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.
 
+### `refute_regex`
+
+This function is similar to `refute_equal` but uses pattern matching instead of
+equality, by wrapping `! [[ value =~ pattern ]]`.
+
+Fail if the value (first parameter) matches the pattern (second parameter).
+
+```bash
+@test 'refute_regex()' {
+  refute_regex 'WhatsApp' 'Threema'
+}
+```
+
+On failure, the value, the pattern and the match are displayed.
+
+```
+@test 'refute_regex()' {
+  refute_regex 'WhatsApp' 'What.'
+}
+
+-- value matches regular expression --
+value    : WhatsApp
+pattern  : What.
+match    : Whats
+case     : sensitive
+--
+```
+
+If the value or pattern is longer than one line then it is displayed in
+*multi-line* 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
+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