diff options
Diffstat (limited to 'extras/hs-test/README.rst')
| -rw-r--r-- | extras/hs-test/README.rst | 98 |
1 files changed, 83 insertions, 15 deletions
diff --git a/extras/hs-test/README.rst b/extras/hs-test/README.rst index 7841211e3ab..c62be5a84aa 100644 --- a/extras/hs-test/README.rst +++ b/extras/hs-test/README.rst @@ -27,7 +27,7 @@ Anatomy of a test case **Action flow when running a test case**: #. It starts with running ``make test``. Optional arguments are VERBOSE, PERSIST (topology configuration isn't cleaned up after test run, use ``make cleanup-hst`` to clean up), - TEST=<test-name> to run a specific test and PARALLEL=[n-cpus]. + TEST=<test-name> to run a specific test and PARALLEL=[n-cpus]. If you want to run multiple specific tests, separate their names with a comma. #. ``make list-tests`` (or ``make help``) shows all tests. #. ``Ginkgo`` looks for a spec suite in the current directory and then compiles it to a .test binary. #. The Ginkgo test framework runs each function that was registered manually using ``Register[SuiteName]Test()``. Each of these functions correspond to a suite. @@ -167,8 +167,8 @@ Modifying the framework // Add custom setup code here - s.ConfigureNetworkTopology("myTopology") - s.LoadContainerTopology("2peerVeth") + s.ConfigureNetworkTopology("myNetworkTopology") + s.LoadContainerTopology("myContainerTopology") } #. In suite file, implement ``SetupTest`` method which gets executed before each test. Starting containers and @@ -216,7 +216,7 @@ Modifying the framework It(testName, func(ctx SpecContext) { s.Log(testName + ": BEGIN") test(&s) - }, SpecTimeout(SuiteTimeout)) + }, SpecTimeout(TestTimeout)) } } }) @@ -237,7 +237,7 @@ Modifying the framework It(testName, Label("SOLO"), func(ctx SpecContext) { s.Log(testName + ": BEGIN") test(&s) - }, SpecTimeout(time.Minute*5)) + }, SpecTimeout(TestTimeout)) }) #. Next step is to add test cases to the suite. For that, see section `Adding a test case`_ above @@ -293,7 +293,23 @@ Alternatively copy the executable from host system to the Docker image, similarl However the tests currently run under test suites which set up topology and containers before actual test is run. For the reason of saving test run time it is not advisable to use aforementioned skip methods and instead, just don't register the test. -**Debugging a test** +**External dependencies** + +* Linux tools ``ip``, ``brctl`` +* Standalone programs ``wget``, ``iperf3`` - since these are downloaded when Docker image is made, + they are reasonably up-to-date automatically +* Programs in Docker images - ``envoyproxy/envoy-contrib`` and ``nginx`` +* ``http_server`` - homegrown application that listens on specified port and sends a test file in response +* Non-standard Go libraries - see ``extras/hs-test/go.mod`` + +Generally, these will be updated on a per-need basis, for example when a bug is discovered +or a new version incompatibility issue occurs. + +Debugging a test +---------------- + +GDB +^^^ It is possible to debug VPP by attaching ``gdb`` before test execution by adding ``DEBUG=true`` like follows: @@ -307,18 +323,70 @@ It is possible to debug VPP by attaching ``gdb`` before test execution by adding If a test consists of more VPP instances then this is done for each of them. +Utility methods +^^^^^^^^^^^^^^^ -**Eternal dependencies** +**Packet Capture** -* Linux tools ``ip``, ``brctl`` -* Standalone programs ``wget``, ``iperf3`` - since these are downloaded when Docker image is made, - they are reasonably up-to-date automatically -* Programs in Docker images - ``envoyproxy/envoy-contrib`` and ``nginx`` -* ``http_server`` - homegrown application that listens on specified port and sends a test file in response -* Non-standard Go libraries - see ``extras/hs-test/go.mod`` +It is possible to use VPP pcap trace to capture received and sent packets. +You just need to add ``EnablePcapTrace`` to ``SetupTest`` method in test suite and ``CollectPcapTrace`` to ``TearDownTest``. +This way pcap trace is enabled on all interfaces and to capture maximum 10000 packets. +Your pcap file will be located in the test execution directory. -Generally, these will be updated on a per-need basis, for example when a bug is discovered -or a new version incompatibility issue occurs. +**Event Logger** + +``clib_warning`` is a handy way to add debugging output, but in some cases it's not appropriate for per-packet use in data plane code. +In this case VPP event logger is better option, for example you can enable it for TCP or session layer in build time. +To collect traces when test ends you just need to add ``CollectEventLogs`` method to ``TearDownTest`` in the test suite. +Your event logger file will be located in the test execution directory. +To view events you can use :ref:`G2 graphical event viewer <eventviewer>` or ``convert_evt`` tool, located in ``src/scripts/host-stack/``, +which convert event logs to human readable text. + +Memory leak testing +^^^^^^^^^^^^^^^^^^^ + +It is possible to use VPP memory traces to diagnose if and where memory leaks happen by comparing of two traces at different point in time. +You can do it by test like following: + +:: + + func MemLeakTest(s *NoTopoSuite) { + s.SkipUnlessLeakCheck() // test is excluded from usual test run + vpp := s.GetContainerByName("vpp").VppInstance + /* do your configuration here */ + vpp.Disconnect() // no goVPP less noise + vpp.EnableMemoryTrace() // enable memory traces + traces1, err := vpp.GetMemoryTrace() // get first sample + s.AssertNil(err, fmt.Sprint(err)) + vpp.Vppctl("test mem-leak") // execute some action + traces2, err := vpp.GetMemoryTrace() // get second sample + s.AssertNil(err, fmt.Sprint(err)) + vpp.MemLeakCheck(traces1, traces2) // compare samples and generate report + } + +To get your memory leak report run following command: + +:: + + $ make test-leak TEST=MemLeakTest + ... + NoTopoSuiteSolo mem_leak_test.go/MemLeakTest [SOLO] + /home/matus/vpp/extras/hs-test/infra/suite_no_topo.go:113 + + Report Entries >> + + SUMMARY: 112 byte(s) leaked in 1 allocation(s) + - /home/matus/vpp/extras/hs-test/infra/vppinstance.go:624 @ 07/19/24 15:53:33.539 + + leak of 112 byte(s) in 1 allocation(s) from: + #0 clib_mem_heap_alloc_aligned + 0x31 + #1 _vec_alloc_internal + 0x113 + #2 _vec_validate + 0x81 + #3 leak_memory_fn + 0x4f + #4 0x7fc167815ac3 + #5 0x7fc1678a7850 + << Report Entries + ------------------------------ .. _ginkgo: https://onsi.github.io/ginkgo/ |