This document outlines some best practices and techniques for testing code which internally uses a Mojo service. It assumes familiarity with the Mojo and Services document.
Suppose we have this Mojo interface:
module example.mojom; interface IncrementerService { Increment(int32 value) => (int32 new_value); }
and this C++ class that uses it:
class Incrementer { public: Incrementer(); void SetServiceForTesting( mojo::PendingRemote<mojom::IncrementerService> service); // The underlying service is async, so this method is too. void Increment(int32_t value, IncrementCallback callback); private; mojo::Remote<mojom::IncrementerService> service_; }; void Incrementer::SetServiceForTesting( mojo::PendingRemote<mojom::IncrementerService> service) { service_.Bind(std::move(service)); } void Incrementer::Increment(int32_t value, IncrementCallback callback) { if (!service_) service_ = LaunchIncrementerService(); service_->Increment(value, std::move(callback)); }
and we wish to swap a test fake in for the underlying IncrementerService, so we can unit-test Incrementer. Specifically, we're trying to write this (silly) test:
// Test that Incrementer correctly handles when the IncrementerService fails to // increment the value. TEST(IncrementerTest, DetectsFailureToIncrement) { Incrementer incrementer; FakeIncrementerService service; // ... somehow use `service` as a test fake for `incrementer` ... incrementer.Increment(0, ...); // ... Get the result and compare it with 0 ... }
This part is fairly straightforward. Mojo generated a class called mojom::IncrementerService, which is normally subclassed by IncrementerServiceImpl (or whatever) in production; we can subclass it ourselves:
class FakeIncrementerService : public mojom::IncrementerService { public: void Increment(int32_t value, IncrementCallback callback) override { // Does not actually increment, for test purposes! std::move(callback).Run(value); } }
We can plug the FakeIncrementerService into our test using:
mojo::Receiver<IncrementerService> receiver{&fake_service}; incrementer->SetServiceForTesting(receiver.BindNewPipeAndPassRemote());
we can invoke it and wait for the response as we usually would:
base::test::TestFuture test_future; incrementer->Increment(0, test_future.GetCallback()); int32_t result = test_future.Get(); EXPECT_EQ(0, result);
... and all is well. However, we might reasonably want a more flexible FakeIncrementerService, which allows for plugging different responses in as the test progresses. In that case, we will actually need to wait twice: once for the request to arrive at the FakeIncrementerService, and once for the response to be delivered back to the Incrementer.
To do that, we can instead structure our fake service like this:
class FakeIncrementerService : public mojom::IncrementerService { public: void Increment(int32_t value, IncrementCallback callback) override { CHECK(!HasPendingRequest()); last_value_ = value; last_callback_ = std::move(callback); if (!signal_.IsReady()) { signal_->SetValue(); } } bool HasPendingRequest() const { return bool(last_callback_); } void WaitForRequest() { if (HasPendingRequest()) { return; } signal_.Clear(); signal_.Wait(); } void AnswerRequest(int32_t value) { CHECK(HasPendingRequest()); std::move(last_callback_).Run(value); } private: int32_t last_value_; IncrementCallback last_callback_; base::test::TestFuture signal_; };
That having been done, our test can now observe the state of the code under test (in this case the Incrementer service) while the mojo request is pending, like so:
FakeIncrementerService service; mojo::Receiver<mojom::IncrementerService> receiver{&service}; Incrementer incrementer; incrementer->SetServiceForTesting(receiver.BindNewPipeAndPassRemote()); incrementer->Increment(1, base::BindLambdaForTesting(...)); // This will do the right thing even if the Increment method later becomes // synchronous, and exercises the same async code paths as the production code // will. service.WaitForRequest(); service.AnswerRequest(service.last_value() + 2); // The lambda passed in above will now asynchronously run somewhere here, // since the response is also delivered asynchronously by mojo.
In some cases, particularly in browser tests, we may want to take an existing, bound mojo::Receiver and intercept certain messages to it. This allows us to:
To accomplish this, Mojo autogenerates an InterceptorForTesting class for each interface that can be subclassed to perform the interception. Continuing with the example above, we can include incrementer_service.mojom-test-utils.h and then use the following to intercept and replace the number to be incremented:
class IncrementerServiceInterceptor : public mojom::IncrementerServiceInterceptorForTesting { public: // We'll assume RealIncrementerService implements the Mojo interface, owns the // the bound mojo::Receiver, and makes it available to use via a testing // method we added named `receiver_for_testing()`. IncrementerServiceInterceptor(RealIncrementerService* service, int32_t value_to_inject) : service_(service), value_to_inject_(value_to_inject), swapped_impl_(service->receiver_for_testing(), this) {} ~IncrementerServiceInterceptor() override = default; mojom::IncrementerService* GetForwardingInterface() override { return service_; } void Increment(int32_t value, IncrementCallback callback) override { GetForwardingInterface()->Increment(value_to_inject_, std::move(callback)); } private: raw_ptr<RealIncrementerService> service_; int32_t value_to_inject_; mojo::test::ScopedSwapImplForTesting< mojo::Receiver<mojom::IncrementerService>> swapped_impl_; };
Both mojo::Remote and mojo::Receiver objects have a FlushForTesting() method that can be used to ensure that queued messages and replies have been sent to the other end of the message pipe, respectively. mojo::Remote objects also have an asynchronous version of this method call FlushAsyncForTesting() that accepts a base::OnceCallback that will be called upon completion. These methods can be particularly helpful in tests where the mojo::Remote and mojo::Receiver might be in separate processes.
