doc: add more notes about new topotests

Add some extra notes to the dev doc section about writing new
topotests: check for OS/kernel support if necessary; avoid
volatile or unstable data like ifindices or link-locals.

Signed-off-by: Mark Stapp <mjs@voltanet.io>

diff --git a/doc/developer/subdir.am b/doc/developer/subdir.am
index f7e4486ef07449febf088ac6ab8a400e3dd1733d..d16420c7e72c644b37a5d08a1bc324fa26ccb05e 100644 (file)
--- a/doc/developer/subdir.am
+++ b/doc/developer/subdir.am
@@ -57,6 +57,7 @@ dev_RSTFILES = \
        doc/developer/tracing.rst \
        doc/developer/testing.rst \
        doc/developer/topotests-snippets.rst \
+       doc/developer/topotests-markers.rst \
        doc/developer/topotests.rst \
        doc/developer/workflow.rst \
        doc/developer/xrefs.rst \

diff --git a/doc/developer/topotests.rst b/doc/developer/topotests.rst
index 93d81548b23986d167e4fb67f349660477b3d5c1..7976a206f7d51c690f32608c11ea9fcb4d977af7 100644 (file)
--- a/doc/developer/topotests.rst
+++ b/doc/developer/topotests.rst
@@ -388,11 +388,19 @@ This is the recommended test writing routine:
 - Format the new code using `black <https://github.com/psf/black>`_
 - Create a Pull Request
 
-.. Note::
+Some things to keep in mind:
+
+- BGP tests MUST use generous convergence timeouts - you must ensure
+  that any test involving BGP uses a convergence timeout of at least
+  130 seconds.
+- Topotests are run on a range of Linux versions: if your test
+  requires some OS-specific capability (like mpls support, or vrf
+  support), there are test functions available in the libraries that
+  will help you determine whether your test should run or be skipped.
+- Avoid including unstable data in your test: don't rely on link-local
+  addresses or ifindex values, for example, because these can change
+  from run to run.
 
-   BGP tests MUST use generous convergence timeouts - you must ensure
-   that any test involving BGP uses a convergence timeout of at least
-   130 seconds.
 
 Topotest File Hierarchy
 """""""""""""""""""""""
@@ -795,7 +803,7 @@ Requirements:
 - Use `black <https://github.com/psf/black>`_ code formatter before creating
   a pull request. This ensures we have a unified code style.
 - Mark test modules with pytest markers depending on the daemons used during the
-  tests (s. Markers)
+  tests (see :ref:`topotests-markers`)
 
 Tips: