diff options
author | Gennadiy Civil <misterg@google.com> | 2019-06-10 14:51:41 (GMT) |
---|---|---|
committer | Gennadiy Civil <misterg@google.com> | 2019-06-10 14:51:41 (GMT) |
commit | fbcb2eb2004dcc581e637b14e07cc4ed5820e9f5 (patch) | |
tree | d80a6430f477bcc25ddacadc9496979f5922466e /googletest/docs | |
parent | 6f79a3b8a7dce9e2fd883ef50c9f36161ff9e9d3 (diff) | |
download | googletest-fbcb2eb2004dcc581e637b14e07cc4ed5820e9f5.zip googletest-fbcb2eb2004dcc581e637b14e07cc4ed5820e9f5.tar.gz googletest-fbcb2eb2004dcc581e637b14e07cc4ed5820e9f5.tar.bz2 |
removing obsolete language from docs, CMake and Bazel is the only supporeted build methods
Diffstat (limited to 'googletest/docs')
-rw-r--r-- | googletest/docs/XcodeGuide.md | 93 | ||||
-rw-r--r-- | googletest/docs/advanced.md | 128 | ||||
-rw-r--r-- | googletest/docs/primer.md | 4 |
3 files changed, 66 insertions, 159 deletions
diff --git a/googletest/docs/XcodeGuide.md b/googletest/docs/XcodeGuide.md deleted file mode 100644 index 1c60a33..0000000 --- a/googletest/docs/XcodeGuide.md +++ /dev/null @@ -1,93 +0,0 @@ - - -This guide will explain how to use the Google Testing Framework in your Xcode projects on Mac OS X. This tutorial begins by quickly explaining what to do for experienced users. After the quick start, the guide goes provides additional explanation about each step. - -# Quick Start # - -Here is the quick guide for using Google Test in your Xcode project. - - 1. Download the source from the [website](https://github.com/google/googletest) using this command: `svn checkout http://googletest.googlecode.com/svn/trunk/ googletest-read-only`. - 1. Open up the `gtest.xcodeproj` in the `googletest-read-only/xcode/` directory and build the gtest.framework. - 1. Create a new "Shell Tool" target in your Xcode project called something like "UnitTests". - 1. Add the gtest.framework to your project and add it to the "Link Binary with Libraries" build phase of "UnitTests". - 1. Add your unit test source code to the "Compile Sources" build phase of "UnitTests". - 1. Edit the "UnitTests" executable and add an environment variable named "DYLD\_FRAMEWORK\_PATH" with a value equal to the path to the framework containing the gtest.framework relative to the compiled executable. - 1. Build and Go. - -The following sections further explain each of the steps listed above in depth, describing in more detail how to complete it including some variations. - -# Get the Source # - -Currently, the gtest.framework discussed here isn't available in a tagged release of Google Test, it is only available in the trunk. As explained at the Google Test [site](https://github.com/google/googletest), you can get the code from anonymous SVN with this command: - -``` -svn checkout http://googletest.googlecode.com/svn/trunk/ googletest-read-only -``` - -Alternatively, if you are working with Subversion in your own code base, you can add Google Test as an external dependency to your own Subversion repository. By following this approach, everyone that checks out your svn repository will also receive a copy of Google Test (a specific version, if you wish) without having to check it out explicitly. This makes the set up of your project simpler and reduces the copied code in the repository. - -To use `svn:externals`, decide where you would like to have the external source reside. You might choose to put the external source inside the trunk, because you want it to be part of the branch when you make a release. However, keeping it outside the trunk in a version-tagged directory called something like `third-party/googletest/1.0.1`, is another option. Once the location is established, use `svn propedit svn:externals _directory_` to set the svn:externals property on a directory in your repository. This directory won't contain the code, but be its versioned parent directory. - -The command `svn propedit` will bring up your Subversion editor, making editing the long, (potentially multi-line) property simpler. This same method can be used to check out a tagged branch, by using the appropriate URL (e.g. `https://github.com/google/googletest/releases/tag/release-1.0.1`). Additionally, the svn:externals property allows the specification of a particular revision of the trunk with the `-r_##_` option (e.g. `externals/src/googletest -r60 http://googletest.googlecode.com/svn/trunk`). - -Here is an example of using the svn:externals properties on a trunk (read via `svn propget`) of a project. This value checks out a copy of Google Test into the `trunk/externals/src/googletest/` directory. - -``` -[Computer:svn] user$ svn propget svn:externals trunk -externals/src/googletest http://googletest.googlecode.com/svn/trunk -``` - -# Add the Framework to Your Project # - -The next step is to build and add the gtest.framework to your own project. This guide describes two common ways below. - - * **Option 1** --- The simplest way to add Google Test to your own project, is to open gtest.xcodeproj (found in the xcode/ directory of the Google Test trunk) and build the framework manually. Then, add the built framework into your project using the "Add->Existing Framework..." from the context menu or "Project->Add..." from the main menu. The gtest.framework is relocatable and contains the headers and object code that you'll need to make tests. This method requires rebuilding every time you upgrade Google Test in your project. - * **Option 2** --- If you are going to be living off the trunk of Google Test, incorporating its latest features into your unit tests (or are a Google Test developer yourself). You'll want to rebuild the framework every time the source updates. to do this, you'll need to add the gtest.xcodeproj file, not the framework itself, to your own Xcode project. Then, from the build products that are revealed by the project's disclosure triangle, you can find the gtest.framework, which can be added to your targets (discussed below). - -# Make a Test Target # - -To start writing tests, make a new "Shell Tool" target. This target template is available under BSD, Cocoa, or Carbon. Add your unit test source code to the "Compile Sources" build phase of the target. - -Next, you'll want to add gtest.framework in two different ways, depending upon which option you chose above. - - * **Option 1** --- During compilation, Xcode will need to know that you are linking against the gtest.framework. Add the gtest.framework to the "Link Binary with Libraries" build phase of your test target. This will include the Google Test headers in your header search path, and will tell the linker where to find the library. - * **Option 2** --- If your working out of the trunk, you'll also want to add gtest.framework to your "Link Binary with Libraries" build phase of your test target. In addition, you'll want to add the gtest.framework as a dependency to your unit test target. This way, Xcode will make sure that gtest.framework is up to date, every time your build your target. Finally, if you don't share build directories with Google Test, you'll have to copy the gtest.framework into your own build products directory using a "Run Script" build phase. - -# Set Up the Executable Run Environment # - -Since the unit test executable is a shell tool, it doesn't have a bundle with a `Contents/Frameworks` directory, in which to place gtest.framework. Instead, the dynamic linker must be told at runtime to search for the framework in another location. This can be accomplished by setting the "DYLD\_FRAMEWORK\_PATH" environment variable in the "Edit Active Executable ..." Arguments tab, under "Variables to be set in the environment:". The path for this value is the path (relative or absolute) of the directory containing the gtest.framework. - -If you haven't set up the DYLD\_FRAMEWORK\_PATH, correctly, you might get a message like this: - -``` -[Session started at 2008-08-15 06:23:57 -0600.] - dyld: Library not loaded: @loader_path/../Frameworks/gtest.framework/Versions/A/gtest - Referenced from: /Users/username/Documents/Sandbox/gtestSample/build/Debug/WidgetFrameworkTest - Reason: image not found -``` - -To correct this problem, go to to the directory containing the executable named in "Referenced from:" value in the error message above. Then, with the terminal in this location, find the relative path to the directory containing the gtest.framework. That is the value you'll need to set as the DYLD\_FRAMEWORK\_PATH. - -# Build and Go # - -Now, when you click "Build and Go", the test will be executed. Dumping out something like this: - -``` -[Session started at 2008-08-06 06:36:13 -0600.] -[==========] Running 2 tests from 1 test case. -[----------] Global test environment set-up. -[----------] 2 tests from WidgetInitializerTest -[ RUN ] WidgetInitializerTest.TestConstructor -[ OK ] WidgetInitializerTest.TestConstructor -[ RUN ] WidgetInitializerTest.TestConversion -[ OK ] WidgetInitializerTest.TestConversion -[----------] Global test environment tear-down -[==========] 2 tests from 1 test case ran. -[ PASSED ] 2 tests. - -The Debugger has exited with status 0. -``` - -# Summary # - -Unit testing is a valuable way to ensure your data model stays valid even during rapid development or refactoring. The Google Testing Framework is a great unit testing framework for C and C++ which integrates well with an Xcode development environment. diff --git a/googletest/docs/advanced.md b/googletest/docs/advanced.md index 604b471..8f230ce 100644 --- a/googletest/docs/advanced.md +++ b/googletest/docs/advanced.md @@ -773,7 +773,7 @@ TEST_F(FooDeathTest, DoesThat) { } ``` -**Availability**: Linux, Windows (requires MSVC 8.0 or above), Cygwin, and Mac +**Availability**: Linux, Windows, Cygwin, and Mac ### Regular Expression Syntax @@ -1452,7 +1452,7 @@ given test suite, whether their definitions come before or *after* the You can see sample7_unittest.cc and sample8_unittest.cc for more examples. -**Availability**: Linux, Windows (requires MSVC 8.0 or above), Mac +**Availability**: Linux, Windows, Mac ### Creating Value-Parameterized Abstract Tests @@ -1575,7 +1575,7 @@ TYPED_TEST(FooTest, HasPropertyA) { ... } You can see sample6_unittest.cc -**Availability**: Linux, Windows (requires MSVC 8.0 or above), Mac +**Availability**: Linux, Windows, Mac ## Type-Parameterized Tests @@ -1651,7 +1651,7 @@ INSTANTIATE_TYPED_TEST_SUITE_P(My, FooTest, int); You can see `sample6_unittest.cc` for a complete example. -**Availability**: Linux, Windows (requires MSVC 8.0 or above), Mac +**Availability**: Linux, Windows, Mac ## Testing Private Code @@ -1817,66 +1817,66 @@ For technical reasons, there are some caveats: 1. `statement` in `EXPECT_FATAL_FAILURE{_ON_ALL_THREADS}()()` cannot return a value. -## Registering tests programmatically - - The `TEST` macros handle the vast majority of all use cases, but there are few -were runtime registration logic is required. For those cases, the framework -provides the `::testing::RegisterTest` that allows callers to register arbitrary -tests dynamically. - This is an advanced API only to be used when the `TEST` macros are insufficient. -The macros should be preferred when possible, as they avoid most of the -complexity of calling this function. - It provides the following signature: - ```c++ -template <typename Factory> -TestInfo* RegisterTest(const char* test_case_name, const char* test_name, - const char* type_param, const char* value_param, - const char* file, int line, Factory factory); -``` - The `factory` argument is a factory callable (move-constructible) object or -function pointer that creates a new instance of the Test object. It handles -ownership to the caller. The signature of the callable is `Fixture*()`, where -`Fixture` is the test fixture class for the test. All tests registered with the -same `test_case_name` must return the same fixture type. This is checked at -runtime. - The framework will infer the fixture class from the factory and will call the -`SetUpTestCase` and `TearDownTestCase` for it. - Must be called before `RUN_ALL_TESTS()` is invoked, otherwise behavior is -undefined. - Use case example: - ```c++ -class MyFixture : public ::testing::Test { - public: - // All of these optional, just like in regular macro usage. - static void SetUpTestCase() { ... } - static void TearDownTestCase() { ... } - void SetUp() override { ... } - void TearDown() override { ... } -}; - class MyTest : public MyFixture { - public: - explicit MyTest(int data) : data_(data) {} - void TestBody() override { ... } - private: - int data_; -}; - void RegisterMyTests(const std::vector<int>& values) { - for (int v : values) { - ::testing::RegisterTest( - "MyFixture", ("Test" + std::to_string(v)).c_str(), nullptr, - std::to_string(v).c_str(), - __FILE__, __LINE__, - // Important to use the fixture type as the return type here. - [=]() -> MyFixture* { return new MyTest(v); }); - } -} -... -int main(int argc, char** argv) { - std::vector<int> values_to_test = LoadValuesFromConfig(); - RegisterMyTests(values_to_test); - ... - return RUN_ALL_TESTS(); -} +## Registering tests programmatically + + The `TEST` macros handle the vast majority of all use cases, but there are few +were runtime registration logic is required. For those cases, the framework +provides the `::testing::RegisterTest` that allows callers to register arbitrary +tests dynamically. + This is an advanced API only to be used when the `TEST` macros are insufficient. +The macros should be preferred when possible, as they avoid most of the +complexity of calling this function. + It provides the following signature: + ```c++ +template <typename Factory> +TestInfo* RegisterTest(const char* test_case_name, const char* test_name, + const char* type_param, const char* value_param, + const char* file, int line, Factory factory); +``` + The `factory` argument is a factory callable (move-constructible) object or +function pointer that creates a new instance of the Test object. It handles +ownership to the caller. The signature of the callable is `Fixture*()`, where +`Fixture` is the test fixture class for the test. All tests registered with the +same `test_case_name` must return the same fixture type. This is checked at +runtime. + The framework will infer the fixture class from the factory and will call the +`SetUpTestCase` and `TearDownTestCase` for it. + Must be called before `RUN_ALL_TESTS()` is invoked, otherwise behavior is +undefined. + Use case example: + ```c++ +class MyFixture : public ::testing::Test { + public: + // All of these optional, just like in regular macro usage. + static void SetUpTestCase() { ... } + static void TearDownTestCase() { ... } + void SetUp() override { ... } + void TearDown() override { ... } +}; + class MyTest : public MyFixture { + public: + explicit MyTest(int data) : data_(data) {} + void TestBody() override { ... } + private: + int data_; +}; + void RegisterMyTests(const std::vector<int>& values) { + for (int v : values) { + ::testing::RegisterTest( + "MyFixture", ("Test" + std::to_string(v)).c_str(), nullptr, + std::to_string(v).c_str(), + __FILE__, __LINE__, + // Important to use the fixture type as the return type here. + [=]() -> MyFixture* { return new MyTest(v); }); + } +} +... +int main(int argc, char** argv) { + std::vector<int> values_to_test = LoadValuesFromConfig(); + RegisterMyTests(values_to_test); + ... + return RUN_ALL_TESTS(); +} ``` ## Getting the Current Test's Name diff --git a/googletest/docs/primer.md b/googletest/docs/primer.md index fb96cdf..10284f8 100644 --- a/googletest/docs/primer.md +++ b/googletest/docs/primer.md @@ -24,8 +24,8 @@ So what makes a good test, and how does googletest fit in? We believe: projects and start to work on a new code base. 1. Tests should be *portable* and *reusable*. Google has a lot of code that is platform-neutral, its tests should also be platform-neutral. googletest - works on different OSes, with different compilers (gcc, icc, and MSVC), with - or without exceptions, so googletest tests can easily work with a variety of + works on different OSes, with different compilers, with + or without exceptions, so googletest tests can work with a variety of configurations. 1. When tests fail, they should provide as much *information* about the problem as possible. googletest doesn't stop at the first test failure. Instead, it |