# Testing in WebRTC This document collects advice and best practices for writing tests in WebRTC, covering GN macros, GoogleTest/GMock usage, and available utilities. ## Configure GN Macros ### Use `rtc_cc_test` for new unit tests As part of the "Small Tests" infrastructure, use `rtc_cc_test` for new unit tests. It defines a library and a standalone binary (prefixed with the folder name and suffixed with `_bin`). To generate the binary, run autoninja with a "\_bin" suffix to the target - `autoninja -C out/Default pc:proxy_unittest_bin` will generate "out/Default/pc_proxy_unittest_bin" as your binary. It should normally have a single source file. Use `rtc_test_suite` to aggregate `rtc_cc_test` targets into larger "mega-targets" for CI/CQ (e.g., `peerconnection_unittests`). Each `rtc_cc_test` targets must be in exactly one `rtc_test_suite` target. Refer to \[add-new-test-binary.md\](add-new-test-binary.md) for details on how to add the binary for a new test suite to the infrastructure. ### Legacy: Using `rtc_test` to define test binaries The `rtc_test` template is the traditional way to define test binaries in WebRTC. It automatically adds `//test:test_main` as a dependency, providing the standard `main()` function for running GoogleTest. - **Example**: ```gn import("//webrtc.gni") rtc_test("my_unittest") { sources = [ "my_unittest.cc" ] deps = [ ":my_library", "//test:test_support", ] } ``` New test suites should be defined using rtc_test_suite and rtc_cc_test. ### Prefer `rtc_library` for test support `rtc_library` is preferred for most targets (including test support code). It automatically switches between `source_set` and `static_library` based on configuration and the `testonly` flag. ## Follow GoogleTest and GMock Best Practices These are documented in the [Google testing blog](https://testing.googleblog.com/). Refer to the [GMock Matchers Reference](https://google.github.io/googletest/reference/matchers.html) for a full list of available matchers. ### In WebRTC, include wrappers instead of raw headers Always include `test/gtest.h` and `test/gmock.h` instead of the raw GoogleTest/GMock headers. These wrappers handle warning suppressions and exports correctly for WebRTC. ### Use `EXPECT_TRUE` and `EXPECT_FALSE` only for booleans Use these macros for pure boolean comparisons only. Do not rely on implicit conversions (e.g., checking if a pointer is non-null). ```cpp {.bad} EXPECT_TRUE(pointer); // BAD: implicit conversion to bool EXPECT_TRUE(integer_value); // BAD: implicit conversion ``` ```cpp {.good} using ::testing::NotNull; EXPECT_NE(pointer, nullptr); EXPECT_THAT(pointer, NotNull()); EXPECT_NE(integer_value, 0); ``` See [the relevant Abseil tips](https://abseil.io/tips/141) for details. Note that `using` at the beginning of the file is [recommended in gmock](https://google.github.io/googletest/gmock_cook_book.html). ### Prefer `EXPECT_THAT` for complex evaluations `EXPECT_EQ`, `EXPECT_LE`, `EXPECT_LT`, `EXPECT_GE`, `EXPECT_GT` are acceptable for simple cases. Prefer `EXPECT_THAT` and matchers for anything with complex evaluations or when better error messages are needed. ```cpp {.bad} EXPECT_TRUE(vec.size() == 1 && vec[0] == "val"); // poor failure message ``` ```cpp {.good} using ::testing::ElementsAre; EXPECT_THAT(vec, ElementsAre("val")); EXPECT_LE(value, 10); // okay for simple cases ``` ### Avoid Yoda matching Always put the **tested value first** and the **constant/expected value last** in all expectations. ```cpp {.bad} EXPECT_EQ(0, value); ``` ```cpp {.good} EXPECT_EQ(value, 0); ``` ### Use `ASSERT_` for fatal conditions Prefer `EXPECT_` for the normal case. This allows you to report several errors from one single test run. Use `ASSERT_` if failing the condition would cause a crash or undefined behavior in subsequent code, or if failing the check would make later tests irrelevant (e.g., checking if a pointer is null before dereferencing it). This is also recommended by the [GoogleTest primer](https://google.github.io/googletest/primer.html#assertions). ### Avoid expectations in helper functions Helper functions in tests that contain expectations (`EXPECT_`/`ASSERT_`) are discouraged. Instead, use matchers to make tests more readable and provide better failure messages. You can create custom matchers in three ways: 1. **Returning a Matcher Combination**: Combine existing matchers. ```cpp auto FirstElementIs(int x) { return ::testing::AllOf( ::testing::Not(::testing::IsEmpty()), ::testing::ResultOf([](const auto& v) { return v.front(); }, ::testing::Eq(x))); } ``` 2. **Using `MATCHER_P` Macros**: For simple parameterized matchers. - Example in [test/fake_encoded_frame.h](../test/fake_encoded_frame.h): ```cpp MATCHER_P(WithId, id, "") { return arg.Id() == id; } ``` 3. **Implementing a Matcher Class**: For complex matchers that need to provide detailed explanations. - Example in [test/near_matcher.h](../test/near_matcher.h) which implements a `NearMatcher` for time types. - **Usage Example**: ```cpp #include "test/near_matcher.h" // ... EXPECT_THAT(actual_timestamp, webrtc::Near(expected_timestamp, TimeDelta::Millis(5))); ``` More information about writing matchers is found in the [GMock cookbook](https://google.github.io/googletest/gmock_cook_book.html#NewMatchers). ## Use WebRTC Testing Utilities ### Use `GlobalSimulatedTimeController` for simulated time Use `GlobalSimulatedTimeController` to run tests that depend on time (e.g., pacing, timeouts) without waiting for real time to pass. It provides a `Clock` and `TaskQueueFactory`. Prefer modern simulated time infrastructure over legacy `ScopedFakeClock`. ### Create an `Environment` using `CreateTestEnvironment` The `Environment` is the modern way to propagate global utilities (like `Clock`, `TaskQueueFactory`, `FieldTrials`) through the codebase. Tests that exercise any component using an `Environment` **must always create** an `Environment` using `webrtc::CreateTestEnvironment` (defined in [test/create_test_environment.h](../test/create_test_environment.h)) and pass it to the components being tested. Using `CreateEnvironment` will cause the test to ignore the command line `force-fieldtrials` flag, so this should not be used in tests unless there are specific reasons for using it. ### Avoid polling, use `WaitUntil` when needed `webrtc::WaitUntil` (located in [test/wait_until.h](../test/wait_until.h)) is a modern utility for waiting for a condition to become true. It is best to avoid polling where possible, but when needed, use `WaitUntil` instead of manual polling or sleeping. It polls a predicate using the `TimeController`. ### Use `RunLoop` for single-threaded async simulation `webrtc::test::RunLoop` (located in `test/run_loop.h`) is a helper class for tests that need to process tasks posted to a task queue but still want to run everything on a single thread. It is useful for simulating async operations simply. ### Select a Scenario Framework Some of the available frameworks: - **`Scenario`** (`test/scenario`): Best for **network and media quality** evaluation (e.g., bandwidth estimation, congestion control). - **`PeerScenario`** (`test/peer_scenario`): Best for **signaling and PeerConnection API** level tests that require multiple threads and a simulated network but want to stay lightweight. **`PCLF** (`api/test/pclf`) is a framework for full integration tests. - \*\*`IntegrationTestHelpers` (`pc/test/integration_test_helpers`) is an older set of tools that is heavily used for PeerConnection-related unit testing. Other frameworks for more specialized purposes also exist. <--! Question: Should we recommend one over the others? --> ### Mocking A lot of classes have existing mocks. Mocks for classes used in `api` live in `api/test`; there are some in `test`, but in general, mocks for internal classes should live close to the class they mock. Mocks should be "pure mocks" using `gmock`. If the test double needs to have code in it, it should be called a fake. See [this testing blog](https://testing.googleblog.com/2013/07/testing-on-toilet-know-your-test-doubles.html) for terminology. General advice on mocking is in the [GMock cookbook](https://google.github.io/googletest/gmock_cook_book.html). ### Leverage Other Utilities - **`FrameGenerator`**: Located in `test/frame_generator.h`; it is useful for generating video frames for testing video pipelines. ## Run Tests ### Use `gtest-parallel` for faster local execution For faster local execution, use `third_party/gtest-parallel/gtest-parallel `. Note that some tests are timing dependent and may be flaky when run under `gtest-parallel`.