base/test/multiprocess_test.h

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