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