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