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