devguide: add page about rust unittests

Part of the task to offer better guidance on how and when to write
unit tests or suricata-verify tests
Also updated linking and index files, as well as testing page to refer
to the unit tests pages

Doc: #4590

diff --git a/doc/devguide/Makefile.am b/doc/devguide/Makefile.am
index 57c9704f61085b6f7682fc0dec7d38b8cd6d7673..9ede0eae4119e856f36a4306a467db5b76598a9a 100644 (file)
--- a/doc/devguide/Makefile.am
+++ b/doc/devguide/Makefile.am
@@ -21,7 +21,8 @@ EXTRA_DIST = \
        codebase/contributing/index.rst \
        codebase/fuzz-testing.rst \
        codebase/testing.rst \
-       codebase/unittests-c.rst
+       codebase/unittests-c.rst \
+       codebase/unittests-rust.rst
 
 if HAVE_SPHINXBUILD
 if HAVE_MSCGEN

diff --git a/doc/devguide/codebase/index.rst b/doc/devguide/codebase/index.rst
index b868bc09a4706d93e275f73ae707651bd9459876..392f367a85752030f7ca044e365c85560acf4501 100644 (file)
--- a/doc/devguide/codebase/index.rst
+++ b/doc/devguide/codebase/index.rst
@@ -9,3 +9,4 @@ Working with the Codebase
    fuzz-testing
    testing
    unittests-c
+   unittests-rust

diff --git a/doc/devguide/codebase/testing.rst b/doc/devguide/codebase/testing.rst
index 662fb0ae6798889c6f2e1212d207b34f906aaa4b..ac844c22a2c8c8125d67dab4ff1f575263559e67 100644 (file)
--- a/doc/devguide/codebase/testing.rst
+++ b/doc/devguide/codebase/testing.rst
@@ -34,8 +34,8 @@ To execute all unit tests (both from C and Rust code), as well as ``libhtp`` one
 
     make check
 
-.. Check the Suricata Devguide on :doc:`unittests-c` or :doc:`unittests-rust` for more on how to write and run unit tests,
-.. considering that the way to do so differs considerably in Suricata, based on the language.
+Check the Suricata Devguide on :doc:`unittests-c` or :doc:`unittests-rust` for more on how to write and run unit tests,
+given that the way to do so differs, depending on the language.
 
 Code Examples
 ^^^^^^^^^^^^^

diff --git a/doc/devguide/codebase/unittests-rust.rst b/doc/devguide/codebase/unittests-rust.rst
new file mode 100644 (file)
index 0000000..4b196f2
--- /dev/null
+++ b/doc/devguide/codebase/unittests-rust.rst
@@ -0,0 +1,90 @@
+*****************
+Unit tests - Rust
+*****************
+
+Rust tests with Cargo check
+===========================
+
+Rust offers a built-in tool for running unit and integration tests. To do so, one makes usage of:
+
+.. code-block:: rust
+
+    cargo test [options][testname][-- test-options]
+
+`The Cargo Book <https://doc.rust-lang.org/cargo/commands/cargo-test.html>`_ explains all options in more detail.
+
+For testing a specific Rust module from Suricata, it suffices to go to the ``rust`` directory and run the above command,
+specifying the desired module (like ``http2``).
+
+.. code-block:: rust
+
+    cargo test http2
+
+The line above will make *rustc* compile the Rust side of Suricata and run unit tests in the ``http2`` rust module.
+
+For running all Suricata unit tests from our Rust codebase, just run ``cargo test``.
+
+Adding unit tests
+=================
+
+ .. note:: If you want to understand *when* to use a unit test, please read the devguide section on :doc:`testing`.
+
+In general, it is preferable to have the unit tests in the same file that they test. At the end of the file, after all other functions. Add a ``tests`` module, if there isn't one yet, and add the ``#[test]`` attribute before the unit test
+function. It is also necessary to import (``use``) the module to test, as well as any other modules used. As seen in the example below:
+
+Example
+-------
+
+From ``nfs > rpc_records.rs``:
+
+.. code-block:: rust
+
+   mod tests {
+        use crate::nfs::rpc_records::*;
+        use nom::Err::Incomplete;
+        use nom::Needed::Size;
+
+        #[test]
+        fn test_partial_input_ok() {
+            let buf: &[u8] = &[
+                0x80, 0x00, 0x00, 0x9c, // flags
+                0x8e, 0x28, 0x02, 0x7e, // xid
+                0x00, 0x00, 0x00, 0x01, // msgtype
+                0x00, 0x00, 0x00, 0x02, // rpcver
+                0x00, 0x00, 0x00, 0x03, // program
+                0x00, 0x00, 0x00, 0x04, // progver
+                0x00, 0x00, 0x00, 0x05, // procedure
+            ];
+            let expected = RpcRequestPacketPartial {
+                hdr: RpcPacketHeader {
+                        frag_is_last: true,
+                        frag_len: 156,
+                        xid: 2384986750,
+                        msgtype: 1
+                    },
+                rpcver: 2,
+                program: 3,
+                progver: 4,
+                procedure: 5
+            };
+            let r = parse_rpc_request_partial(buf);
+            match r {
+                Ok((rem, hdr)) => {
+                    assert_eq!(rem.len(), 0);
+                    assert_eq!(hdr, expected);
+                },
+                _ => { panic!("failed {:?}",r); }
+            }
+        }
+   }
+
+Once that is done, Rust should recognize the new test. If you want to check a single test, run::
+
+    cargo test module::test_name
+
+or even::
+
+    cargo test test_name
+
+if you know it's a unique function name. Following the same idea, it is also possible to test specific modules or
+submodules.