From 3b8ca1d5c417bd51eec94724330b4069447d7064 Mon Sep 17 00:00:00 2001
From: Arne Welzel <arne.welzel@corelight.com>
Date: Fri, 13 Oct 2023 18:28:53 +0200
Subject: [PATCH] statements: Add assert

Closes #199
---
 script-reference/assert_1.zeek  | 18 ++++++++++++
 script-reference/statements.rst | 52 +++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 script-reference/assert_1.zeek

diff --git a/script-reference/assert_1.zeek b/script-reference/assert_1.zeek
new file mode 100644
index 000000000..dff0dee55
--- /dev/null
+++ b/script-reference/assert_1.zeek
@@ -0,0 +1,18 @@
+event test_1() {
+	assert 3 == 3;
+	local x = 37;
+	assert x > 40;
+	print "not reached";
+}
+
+event test_2() {
+	assert 2 == 2;
+	local x = 37;
+	assert x > 40, fmt("%s is not greater than 40", x);
+	print "not reached";
+}
+
+event zeek_init() {
+	schedule 0.01sec { test_1() };
+	schedule 0.02sec { test_2() };
+}
diff --git a/script-reference/statements.rst b/script-reference/statements.rst
index 3bac09619..2ea9fb690 100644
--- a/script-reference/statements.rst
+++ b/script-reference/statements.rst
@@ -493,6 +493,9 @@ Here are the statements that the Zeek scripting language supports.
   * - :zeek:keyword:`add`, :zeek:keyword:`delete`
     - Add or delete elements
 
+  * - :zeek:keyword:`assert`
+    - Runtime assertion
+
   * - :zeek:keyword:`print`
     - Print to stdout or a file
 
@@ -533,6 +536,55 @@ Example:
     add myset["test"];
 
 
+.. zeek:keyword:: assert
+
+assert
+~~~~~~
+
+.. versionadded:: 6.1
+
+The ``assert`` statement can be used for runtime assertion checks or as a building
+block for a testing framework. It takes an expression ``expr`` of type
+:zeek:see:`bool` and an optional message of type :zeek:see:`string`.
+If ``expr`` at runtime evaluates to ``F``, the string representation
+of the expression and the given message, if any, are logged
+via :zeek:see:`Reporter::error` by default.
+
+Script execution for a given event handler stops with a failing ``assert`` statement
+comparable to a scripting runtime error after generating the log.
+
+Example:
+
+.. literalinclude:: assert_1.zeek
+   :language: zeek
+   :linenos:
+   :tab-width: 4
+
+This script prints the following messages to stderr, as well as logging them to
+``reporter.log``.
+
+.. code-block:: console
+
+   $ zeek assert_1.zeek
+   error in ./assert_1.zeek, line 6: assertion failure: 40 < x
+   error in ./assert_1.zeek, line 12: assertion failure: 40 < x (37 is not greater than 40)
+
+.. note::
+
+   Zeek's exit code in this example will be ``0``, indicating success.
+   Script errors other than those in a ``zeek_init()`` handler are not
+   reflected in Zeek's exit code.
+
+
+The logging behavior of failing assert statements can be customized using the
+:zeek:see:`assertion_failure` or zeek:see:`assertion_result` hook.
+Using the :zeek:see:`break` statement in either hook allows for suppression
+of the the default log generation.
+The :zeek:see:`assertion_result` hook is targeted for testing frameworks as it
+is likely prohibitively expensive for use in a live production environment due
+to being invoked for every ``assert`` statement execution.
+
+
 .. zeek:keyword:: break
 
 break