topotest: add writing tests tips

Add two tips to help improve test code quality:
1) Store function returns for later inspection
2) Identify what failed using the assert message

diff --git a/tests/topotests/GUIDELINES.md b/tests/topotests/GUIDELINES.md
index 5f745ae7cebc2d821911cad826d9aecad3512734..1566705bc1b8e1610f6e29a1b0786dbbb856a7a3 100644 (file)
--- a/tests/topotests/GUIDELINES.md
+++ b/tests/topotests/GUIDELINES.md
@@ -419,6 +419,34 @@ Requirements:
 * Tests must be able to run without any interaction. To make sure your test
   conforms with this, run it without the `-s` parameter.
 
+Tips:
+
+* Keep results in stack variables, so people inspecting code with `pdb` can
+  easily print their values.
+
+  Don't do this:
+
+  ```py
+  assert foobar(router1, router2)
+  ```
+
+  Do this instead:
+
+  ```py
+  result = foobar(router1, router2)
+  assert result
+  ```
+
+* Use `assert` messages to indicate where the test failed.
+
+  Example:
+
+  ```py
+  for router in router_list:
+      # ...
+      assert condition, 'Router "{}" condition failed'.format(router.name)
+  ```
+
 
 ### Debugging Execution