3.3 Testing ns-3

You can run the unit tests of the ns-3 distribution by running the “–check” option,

  ./waf --check

These tests are run in parallel by waf, so the summary, “Ran n tests” will appear as soon as all of the tasks are launched, but you should eventually see a report saying that,

  C++ UNIT TESTS: all 33 tests passed.

This is the important message.

You will also see output from the test runner and waf task sequence numbers the output will actually look something like,

  Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
  [707/709] get-unit-tests-list
  [708/709] run-python-unit-tests
  [709/709] print-introspected-doxygen
  [710/743] run-unit-test(AddressHelper)
  [711/743] run-unit-test(Wifi)
  ...........
  ----------------------------------------------------------------------
  Ran 11 tests in 0.003s
  
  OK
  [712/743] run-unit-test(DcfManager)
  [713/743] run-unit-test(MacRxMiddle)
  [714/743] run-unit-test(Ipv4ListRouting)

  ...

  [739/743] run-unit-test(RandomVariable)
  [740/743] run-unit-test(Object)
  [741/743] run-unit-test(Ptr)
  [742/743] run-unit-test(Callback)
  [743/743] collect-unit-tests-results
  C++ UNIT TESTS: all 33 tests passed.
  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
  'build' finished successfully (1.799s)

This command is typically run by users to quickly verify that an ns-3 distribution has built correctly.

You can also run our regression test suite to ensure that your distribution and toolchain have produced binaries that generate output that is identical to known-good reference output files. You downloaded these reference traces to your machine during the ./download.py process above. (Warning: The ns-3.2 and ns-3.3 releases do not use the ns-3-allinone environment and require you to be online when you run regression tests because hey dynamically synchronize the reference traces directory with an online repository immediately prior to the run).

During regression testing Waf will run a number of tests that generate what we call trace files. The content of these trace files are compared with the reference traces. If they are identical, the regression tests report a PASS status. If a regression test fails you will see a FAIL indication along with a pointer to the offending trace file and its associated reference trace file along with a suggestion on diff parameters and options in order to see what has gone awry. If the error was discovered in a pcap file, it will be useful to convert the pcap files to text using tcpdump prior to comparison.

Some regression tests may be SKIPped if the required support is not present.

Note that the regression tests are also run in parallel and so the messages may be interleaved.

To run the regression tests, you provide Waf with the regression flag.

  ./waf --regression

You should see messages indicating that many tests are being run and are passing.

  Entering directory `repos/ns-3-allinone/ns-3-dev/build'
  [647/669] regression-test (test-csma-bridge)
  [648/669] regression-test (test-csma-broadcast)
  [649/669] regression-test (test-csma-multicast)
  [650/669] regression-test (test-csma-one-subnet)
  PASS test-csma-multicast
  [651/669] regression-test (test-csma-packet-socket)
  PASS test-csma-bridge
  ...
  Regression testing summary:
  PASS: 22 of 22 tests passed
  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-3.5-tutorial/ns-3-dev/build'
  'build' finished successfully (25.826s)

If you want to take a look at an example of what might be checked during a regression test, you can do the following:

  cd build/debug/regression/traces/second.ref
  tcpdump -nn -tt -r second-2-0.pcap

The output should be clear to anyone who is familiar with tcpdump or net sniffers. We'll have much more to say on pcap files later in this tutorial.

Remember to cd back into the top-level ns-3 directory after you are done:

  cd ../../../../..

This document was generated on July, 4 2009 using texi2html 1.78.