blob: fc7cf28251f1397c9768ff8a95d8066af82ac729 [file] [log] [blame]
// Copyright 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// TestBrowserThreadBundle is a convenience class for creating a set of
// TestBrowserThreads and a task scheduler in unit tests. For most tests, it is
// sufficient to just instantiate the TestBrowserThreadBundle as a member
// variable. It is a good idea to put the TestBrowserThreadBundle as the first
// member variable in test classes, so it is destroyed last, and the test
// threads always exist from the perspective of other classes.
// By default, all of the created TestBrowserThreads will be backed by a single
// shared MessageLoop. If a test truly needs separate threads, it can do so by
// passing the appropriate combination of option values during the
// TestBrowserThreadBundle construction. TaskScheduler tasks always run on
// dedicated threads.
// To synchronously run tasks from the shared MessageLoop:
// ... until there are no undelayed tasks in the shared MessageLoop:
// base::RunLoop::RunUntilIdle();
// ... until there are no undelayed tasks in the shared MessageLoop, in
// TaskScheduler (excluding tasks not posted from the shared MessageLoop's
// thread or TaskScheduler):
// content::RunAllTasksUntilIdle();
// ... until a condition is met:
// base::RunLoop run_loop;
// // Runs until a task running in the shared MessageLoop calls
// // run_loop.Quit() or runs run_loop.QuitClosure() (&run_loop or
// // run_loop.QuitClosure() must be kept somewhere accessible by that task).
// run_loop.Run();
// To wait until there are no pending undelayed tasks in TaskScheduler, without
// running tasks from the shared MessageLoop:
// base::TaskScheduler::GetInstance()->FlushForTesting();
// The destructor of TestBrowserThreadBundle runs remaining TestBrowserThreads
// tasks and remaining task scheduler tasks.
// If a test needs a MessageLoopForIO on the main thread, it should use the
// IO_MAINLOOP option. Most of the time, IO_MAINLOOP avoids needing to use a
// For some tests it is important to emulate real browser startup. During real
// browser startup, the main MessageLoop and the TaskScheduler are created
// before browser threads. Passing DONT_CREATE_BROWSER_THREADS to constructor
// will delay creating browser threads until the test explicitly calls
// CreateBrowserThreads().
// DONT_CREATE_BROWSER_THREADS should only be used when the options specify at
// least one real thread other than the main thread.
// TestBrowserThreadBundle may be instantiated in a scope where there is already
// a base::test::ScopedTaskEnvironment. In that case, it will use the
// MessageLoop and the TaskScheduler provided by this
// base::test::ScopedTaskEnvironment instead of creating its own. The ability to
// have a base::test::ScopedTaskEnvironment and a TestBrowserThreadBundle in the
// same scope is useful when a fixture that inherits from a fixture that
// provides a base::test::ScopedTaskEnvironment needs to add support for browser
// threads.
// Basic usage:
// class MyTestFixture : public testing::Test {
// public:
// (...)
// protected:
// // Must be the first member (or at least before any member that cares
// // about tasks) to be initialized first and destroyed last. protected
// // instead of private visibility will allow controlling the task
// // environment (e.g. clock) once such features are added (see
// // base::test::ScopedTaskEnvironment for details), until then it at least
// // doesn't hurt :).
// content::TestBrowserThreadBundle test_browser_thread_bundle_;
// // Other members go here (or further below in private section.)
// };
#include <memory>
#include "base/macros.h"
#include "build/build_config.h"
namespace base {
namespace test {
class ScopedTaskEnvironment;
} // namespace test
#if defined(OS_WIN)
namespace win {
class ScopedCOMInitializer;
} // namespace win
} // namespace base
namespace content {
class TestBrowserThread;
// Note: to drive these threads (e.g. run all tasks until idle), see
// content/public/test/test_utils.h.
class TestBrowserThreadBundle {
// Used to specify the type of MessageLoop that backs the UI thread, and
// which of the named BrowserThreads should be backed by a real
// threads. The UI thread is always the main thread in a unit test.
enum Options {
IO_MAINLOOP = 1 << 0,
REAL_IO_THREAD = 1 << 2,
explicit TestBrowserThreadBundle(int options);
// Creates browser threads; should only be called from other classes if the
// DONT_CREATE_BROWSER_THREADS option was used when the bundle was created.
void CreateBrowserThreads();
void Init();
std::unique_ptr<base::test::ScopedTaskEnvironment> scoped_task_environment_;
std::unique_ptr<TestBrowserThread> ui_thread_;
std::unique_ptr<TestBrowserThread> file_thread_;
std::unique_ptr<TestBrowserThread> process_launcher_thread_;
std::unique_ptr<TestBrowserThread> io_thread_;
int options_;
bool threads_created_;
#if defined(OS_WIN)
std::unique_ptr<base::win::ScopedCOMInitializer> com_initializer_;
} // namespace content