Unit testing

Why?

• MUCH faster than integration tests.
• Runs as part of build process.
• Allows testing specific error conditions that are difficult to trigger under normal operating conditions.
  • e.g. out of memory errors etc.
• Allows testing different device compositions without defining multiple example applications.
  • e.g. feature combinations not in example apps.

Unit testing in the SDK - nlUnitTest

The following example gives a small demonstration of how to use nlUnitTest to write a unit test

#include <lib/support/UnitTestContext.h>
#include <lib/support/UnitTestRegistration.h>
#include <nlunit-test.h>

class YourTestContext : public Test::AppContext {
   ...
};


static void TestName(nlTestSuite * apSuite, void * apContext) {
    // If you register the test suite with a context, cast
    // apContext as appropriate
    YourTestContext * ctx = static_cast<YourTestContext *>(aContext);

    // Do some test things here, then check the results using NL_TEST_ASSERT
    NL_TEST_ASSERT(apSuite, <boolean condition>)
}

static const nlTest sTests[] =
{
    NL_TEST_DEF("TestName", TestName), // Can have multiple of these
    NL_TEST_SENTINEL() // If you forget this, you’re going to have a bad time
};

nlTestSuite sSuite =
{
    "TheNameOfYourTestSuite", // Test name
    &sTests[0], // The list of tests to run
    TestContext::Initialize, // Runs before all the tests (can be nullptr)
    TestContext::Finalize // Runs after all the tests (can be nullptr)
};

int YourTestSuiteName()
{
    return chip::ExecuteTestsWithContext<YourTestContext>(&sSuite); // or “without”
}

CHIP_REGISTER_TEST_SUITE(YourTestSuiteName)

Each test gets an nlTestSuite object (apSuite) that is passed into the test assertions, and a void* context (apContext) that is yours to do with as you require.

The apContext should be derived from Test::AppContext

See TestSpan.cpp for a great example of a good unit test.

nlUnitTest - Compiling and running

• Add to src/some_directory/tests/BUILD.gn
  • chip_test_suite_using_nltest(“tests”)
    • See for example src/lib/support/tests/BUILD.gn
• ./gn_build.sh will build and run all tests
  • CI runs this, so any unit tests that get added will automatically be added to the CI
• Test binaries are compiled into:
  • out/debug/<host_compiler>/tests
  • e.g. out/debug/linux_x64_clang/tests
• Tests are run when ./gn_build.sh runs, but you can run them individually in a debugger from their location.

Debugging unit tests

• After running ./gn_build.sh, test binaries are compiled into
  • out/debug/<host_compiler>/tests
  • e.g. out/debug/linux_x64_clang/tests
• Individual binaries, can be run through regular tools:
  • gdb
  • valgrind
  • Your favorite tool that you tell everyone about.

Utilities

We have a small number of unit testing utilities that should be used in unit tests.

Consider adding more utilities for general use if you require them for your tests.

Mock clock

The mock clock is located in src/system/SystemClock.h as System::Clock::Internal::MockClock.

To use the mock clock, use the chip::System::SystemClock() function as normal. In the test, instantiate a MockClock and use the SetSystemClockForTesting to inject the clock. The Set and Advance functions in the MockClock can then be used to set exact times for testing. This allows testing specific edge conditions in tests, helps reduce test flakiness due to race conditions, and reduces the time required for testing as tests no long require real-time waits.

TestPersistentStorageDelegate

The TestPersistentStorageDelegate is an in-memory version of storage that easily allows removal of keys, presence checks, etc. It is available at src/lib/support/TestPersistentStorageDelegate.h