multiprocess_test.h 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150
  1. // Copyright (c) 2012 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 BASE_TEST_MULTIPROCESS_TEST_H_
  5. #define BASE_TEST_MULTIPROCESS_TEST_H_
  6. #include <string>
  7. #include "base/process/launch.h"
  8. #include "base/process/process.h"
  9. #include "build/build_config.h"
  10. #include "testing/platform_test.h"
  11. namespace base {
  12. class CommandLine;
  13. // Helpers to spawn a child for a multiprocess test and execute a designated
  14. // function. Use these when you already have another base class for your test
  15. // fixture, but you want (some) of your tests to be multiprocess (otherwise you
  16. // may just want to derive your fixture from |MultiProcessTest|, below).
  17. //
  18. // Use these helpers as follows:
  19. //
  20. // TEST_F(MyTest, ATest) {
  21. // CommandLine command_line(
  22. // base::GetMultiProcessTestChildBaseCommandLine());
  23. // // Maybe add our own switches to |command_line|....
  24. //
  25. // LaunchOptions options;
  26. // // Maybe set some options (e.g., |start_hidden| on Windows)....
  27. //
  28. // // Start a child process and run |a_test_func|.
  29. // base::Process test_child_process =
  30. // base::SpawnMultiProcessTestChild("a_test_func", command_line,
  31. // options);
  32. //
  33. // // Do stuff involving |test_child_process| and the child process....
  34. //
  35. // int rv = -1;
  36. // ASSERT_TRUE(base::WaitForMultiprocessTestChildExit(test_child_process,
  37. // TestTimeouts::action_timeout(), &rv));
  38. // EXPECT_EQ(0, rv);
  39. // }
  40. //
  41. // // Note: |MULTIPROCESS_TEST_MAIN()| is defined in
  42. // // testing/multiprocess_func_list.h.
  43. // MULTIPROCESS_TEST_MAIN(a_test_func) {
  44. // // Code here runs in a child process....
  45. // return 0;
  46. // }
  47. //
  48. // If you need to terminate the child process, use the
  49. // TerminateMultiProcessTestChild method to ensure that test will work on
  50. // Android.
  51. // Spawns a child process and executes the function |procname| declared using
  52. // |MULTIPROCESS_TEST_MAIN()| or |MULTIPROCESS_TEST_MAIN_WITH_SETUP()|.
  53. // |command_line| should be as provided by
  54. // |GetMultiProcessTestChildBaseCommandLine()| (below), possibly with arguments
  55. // added. Note: On Windows, you probably want to set |options.start_hidden|.
  56. Process SpawnMultiProcessTestChild(const std::string& procname,
  57. const CommandLine& command_line,
  58. const LaunchOptions& options);
  59. // Gets the base command line for |SpawnMultiProcessTestChild()|. To this, you
  60. // may add any flags needed for your child process.
  61. CommandLine GetMultiProcessTestChildBaseCommandLine();
  62. // Waits for the child process to exit. Returns true if the process exited
  63. // within |timeout| and sets |exit_code| if non null.
  64. bool WaitForMultiprocessTestChildExit(const Process& process,
  65. TimeDelta timeout,
  66. int* exit_code);
  67. // Terminates |process| with |exit_code|. If |wait| is true, this call blocks
  68. // until the process actually terminates.
  69. bool TerminateMultiProcessTestChild(const Process& process,
  70. int exit_code,
  71. bool wait);
  72. #if BUILDFLAG(IS_ANDROID)
  73. // Returns whether the child process exited cleanly from the main runloop.
  74. bool MultiProcessTestChildHasCleanExit(const Process& process);
  75. #endif
  76. // MultiProcessTest ------------------------------------------------------------
  77. // A MultiProcessTest is a test class which makes it easier to
  78. // write a test which requires code running out of process.
  79. //
  80. // To create a multiprocess test simply follow these steps:
  81. //
  82. // 1) Derive your test from MultiProcessTest. Example:
  83. //
  84. // class MyTest : public MultiProcessTest {
  85. // };
  86. //
  87. // TEST_F(MyTest, TestCaseName) {
  88. // ...
  89. // }
  90. //
  91. // 2) Create a mainline function for the child processes and include
  92. // testing/multiprocess_func_list.h.
  93. // See the declaration of the MULTIPROCESS_TEST_MAIN macro
  94. // in that file for an example.
  95. // 3) Call SpawnChild("foo"), where "foo" is the name of
  96. // the function you wish to run in the child processes.
  97. // That's it!
  98. class MultiProcessTest : public PlatformTest {
  99. public:
  100. MultiProcessTest();
  101. MultiProcessTest(const MultiProcessTest&) = delete;
  102. MultiProcessTest& operator=(const MultiProcessTest&) = delete;
  103. protected:
  104. // Run a child process.
  105. // 'procname' is the name of a function which the child will
  106. // execute. It must be exported from this library in order to
  107. // run.
  108. //
  109. // Example signature:
  110. // extern "C" int __declspec(dllexport) FooBar() {
  111. // // do client work here
  112. // }
  113. //
  114. // Returns the child process.
  115. Process SpawnChild(const std::string& procname);
  116. // Run a child process using the given launch options.
  117. //
  118. // Note: On Windows, you probably want to set |options.start_hidden|.
  119. Process SpawnChildWithOptions(const std::string& procname,
  120. const LaunchOptions& options);
  121. // Set up the command line used to spawn the child process.
  122. // Override this to add things to the command line (calling this first in the
  123. // override).
  124. // Note that currently some tests rely on this providing a full command line,
  125. // which they then use directly with |LaunchProcess()|.
  126. // TODO(viettrungluu): Remove this and add a virtual
  127. // |ModifyChildCommandLine()|; make the two divergent uses more sane.
  128. virtual CommandLine MakeCmdLine(const std::string& procname);
  129. };
  130. } // namespace base
  131. #endif // BASE_TEST_MULTIPROCESS_TEST_H_