ipc_test_sink.h 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141
  1. // Copyright (c) 2011 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef IPC_IPC_TEST_SINK_H_
  5. #define IPC_IPC_TEST_SINK_H_
  6. #include <stddef.h>
  7. #include <stdint.h>
  8. #include <utility>
  9. #include <vector>
  10. #include "base/observer_list.h"
  11. #include "build/build_config.h"
  12. #include "ipc/ipc_channel.h"
  13. namespace IPC {
  14. class Message;
  15. // This test sink provides a "sink" for IPC messages that are sent. It allows
  16. // the caller to query messages received in various different ways. It is
  17. // designed for tests for objects that use the IPC system.
  18. //
  19. // Typical usage:
  20. //
  21. // test_sink.ClearMessages();
  22. // do_something();
  23. //
  24. // // We should have gotten exactly one update state message.
  25. // EXPECT_TRUE(test_sink.GetUniqeMessageMatching(ViewHostMsg_Update::ID));
  26. // // ...and no start load messages.
  27. // EXPECT_FALSE(test_sink.GetFirstMessageMatching(ViewHostMsg_Start::ID));
  28. //
  29. // // Now inspect a message. This assumes a message that was declared like
  30. // // this: IPC_MESSAGE_ROUTED2(ViewMsg_Foo, bool, int)
  31. // IPC::Message* msg = test_sink.GetFirstMessageMatching(ViewMsg_Foo::ID));
  32. // ASSERT_TRUE(msg);
  33. // bool first_param;
  34. // int second_param;
  35. // ViewMsg_Foo::Read(msg, &first_param, &second_param);
  36. //
  37. // // Go on to the next phase of the test.
  38. // test_sink.ClearMessages();
  39. //
  40. // To read a sync reply, do this:
  41. //
  42. // IPC::Message* msg = test_sink.GetUniqueMessageMatching(IPC_REPLY_ID);
  43. // ASSERT_TRUE(msg);
  44. // base::TupleTypes<ViewHostMsg_Foo::ReplyParam>::ValueTuple reply_data;
  45. // EXPECT_TRUE(ViewHostMsg_Foo::ReadReplyParam(msg, &reply_data));
  46. //
  47. // You can also register to be notified when messages are posted to the sink.
  48. // This can be useful if you need to wait for a particular message that will
  49. // be posted asynchronously. Example usage:
  50. //
  51. // class MyListener : public IPC::Listener {
  52. // public:
  53. // MyListener(const base::RepeatingClosure& closure)
  54. // : message_received_closure_(closure) {}
  55. // virtual bool OnMessageReceived(const IPC::Message& msg) {
  56. // <do something with the message>
  57. // message_received_closure_.Run();
  58. // return false; // to store the message in the sink, or true to drop it
  59. // }
  60. // private:
  61. // base::RepeatingClosure message_received_closure_;
  62. // };
  63. //
  64. // base::RunLoop run_loop;
  65. // MyListener listener(run_loop.QuitClosure());
  66. // test_sink.AddFilter(&listener);
  67. // StartSomeAsynchronousProcess(&test_sink);
  68. // run_loop.Run();
  69. // <inspect the results>
  70. // ...
  71. //
  72. // To hook up the sink, all you need to do is call OnMessageReceived when a
  73. // message is received.
  74. class TestSink : public Channel {
  75. public:
  76. TestSink();
  77. TestSink(const TestSink&) = delete;
  78. TestSink& operator=(const TestSink&) = delete;
  79. ~TestSink() override;
  80. // Interface in IPC::Channel. This copies the message to the sink and then
  81. // deletes it.
  82. bool Send(IPC::Message* message) override;
  83. [[nodiscard]] bool Connect() override;
  84. void Close() override;
  85. // Used by the source of the messages to send the message to the sink. This
  86. // will make a copy of the message and store it in the list.
  87. bool OnMessageReceived(const Message& msg);
  88. // Returns the number of messages in the queue.
  89. size_t message_count() const { return messages_.size(); }
  90. // Clears the message queue of saved messages.
  91. void ClearMessages();
  92. // Returns the message at the given index in the queue. The index may be out
  93. // of range, in which case the return value is NULL. The returned pointer will
  94. // only be valid until another message is received or the list is cleared.
  95. const Message* GetMessageAt(size_t index) const;
  96. // Returns the first message with the given ID in the queue. If there is no
  97. // message with the given ID, returns NULL. The returned pointer will only be
  98. // valid until another message is received or the list is cleared.
  99. const Message* GetFirstMessageMatching(uint32_t id) const;
  100. // Returns the message with the given ID in the queue. If there is no such
  101. // message or there is more than one of that message, this will return NULL
  102. // (with the expectation that you'll do an ASSERT_TRUE() on the result).
  103. // The returned pointer will only be valid until another message is received
  104. // or the list is cleared.
  105. const Message* GetUniqueMessageMatching(uint32_t id) const;
  106. // Adds the given listener as a filter to the TestSink.
  107. // When a message is received by the TestSink, it will be dispatched to
  108. // the filters, in the order they were added. If a filter returns true
  109. // from OnMessageReceived, subsequent filters will not receive the message
  110. // and the TestSink will not store it.
  111. void AddFilter(Listener* filter);
  112. // Removes the given filter from the TestSink.
  113. void RemoveFilter(Listener* filter);
  114. private:
  115. // The actual list of received messages.
  116. std::vector<Message> messages_;
  117. base::ObserverList<Listener>::Unchecked filter_list_;
  118. };
  119. } // namespace IPC
  120. #endif // IPC_IPC_TEST_SINK_H_