Home | History | Annotate | Download | only in test 
      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_
    133