Unity(纯C语言单元测试框架！不是那个Unity3d)入门文档

译者注：译者博客(http://blog.csdn.net/lin_strong)，转载请保留这条。此为Unity手册的翻译，仅供学习交流使用，请勿用于商业用途。
翻译的资料是公开的，在docs/UnityGettingStartedGuide.md，我想应该不会有什么版权问题，如涉及版权问题，请联系我删除文章。

Unity - 入门

欢迎

恭喜。你现在是你那堆bit的光荣的主人了！你准备对你的那些1和0做些什么呢？这篇文档
应该能够帮助你决定这些。

Unity是一个单元测试框架。目标是精简而强大。Unity测试框架的内核是三个文件：单个C
文件和两个头文件。它们相互合作提供许多函数和宏以使得测试更顺滑。

Unity的设计是跨平台的。它尽可能地遵从C标准，同时提供对许多不守规矩的嵌入式C编译器
的支持。Unity已被用在许多编译器上，包括GCC、IAR、Clang、Green Hills、 Microchip和
MS Visual Studio。将其移植到一个新目标上不需要太多工作量。

文档综述

Unity 断言参考文档

这篇文档将带你看遍Unity提供的所有断言选项。这是你单元测试的面包黄油。你将在断言上
花费比Unity其他部分更多的时间。

Unity 断言欺骗表

这篇文档是之前那个文档中各种断言的一个删减的总结表。特别适合打印出来以备参考。

Unity 配置向导

当你打算在一个新目标或编译器上使用Unity时，这篇文档是你要参考的。它会将你看遍配置
选项，帮助你定制你自己的测试环境以满足你的需求。

Unity Helper 脚本

这盘文档描述了helper脚本，helper脚本有助于简化你的测试工作流。它描述了在你的Unity
安装路径下auto文件夹内的那些可用的Ruby脚本。使用Unity并不需要用到Ruby以及这些脚本。
它们只是给想用的人提供一些便利而已。

Unity License

开源项目难道能没有license文件？这篇简短的文档描述了在你使用这个软件时应该同意的条
款。基本上，我们希望不管你想在什么上下文中使用它，它都能对你很有帮助，但是如果你
遇到了问题，请不要责备我们。

文件夹综述

如果你是从Github或其他类似的地方获取Unity的，你很可能被眼前的一堆吓了一跳。
别担心，Unity本身十分的小。其他部分之所以在这只是为了让你的生活过的更好些。
你可以忽视它们或使用它们，全凭你自己做主。这里是工程中所有东西的综述。

• src - 这是你关心的代码！这个文件夹包含一个C文件以及两个头文件。这三个文件 是 Unity。
• docs - 你正在读这个文档，所以可能你是自己进到这个文件夹中的。这里放着所有的文档。
• examples - 这里包含一些使用Unity的示例。
• extras - 这些是可选的Unity插件，它们不是内核工程的一部分。如果你是通过James Grenning的
  书找到我们的，你会想看看这里。
• test - 这里是Unity和它的所有脚本被测试的地方。如果你只是在用Unity，很可能你永远不需要
  看这个文件夹。如果你是团队中负责把Unity移植到新工具链的中奖者，这里可以帮助你验证所有东西
  都被合理地配置了。
• auto - 在这里你将发现一些有用的Ruby脚本，它们可以简化你的测试工作。他们完全只是可选的，
  不用它们照样可以使用Unity。

怎么创建一个测试文件

测试文件都是C文件。大部分情况下，你将为每个你想要测试的C模块创建一个测试文件。
测试文件应该include unity.h以及你要测试的C模块的头文件。

下一步，一个测试文件将包含一个setUp()以及tearDown()函数。setUp函数可以包含任何你
想要在每个测试之前运行的东西。tearDown函数可以包含任何你想要在每个测试之后运行的东西。
两个函数都不接受任何参数，也不返回东西。如果你在使用一个将这些函数配置为可选的编译器，
你也许可以不实现他们。不确定？试一试不就知道了。如果你的编译器抱怨说它在链接时找不到
setUp或tearDown，那你就知道你起码需要为它们创建一个空的函数了。

文件的主体将会是一系列的测试函数。测试函数遵从以下命名约定，以"test_"或"spec_"为开头。
不是必须按照这种方式命名它们，但是这样会使得其他开发者更容易看出哪些函数是测试。同样的，
Unity或Ceedling自带的自动化脚本将默认通过这种前缀的方式来寻找测试函数。测试函数都不接受
任何参数，也不返回东西。所有的测试计数是由Unity内部处理的。

最终，在你的测试文件的最底下，你将写一个main()函数。这个函数将调用UNITY_BEGIN()，
然后为每个测试调用RUN_TEST，然后最终是UNITY_END()。这是实际上触发每个测试函数运行
的地方，所以重要的是，每个函数都要有它自己的RUN_TEST。

把每个测试加进main函数的过程真是很无聊。如果你喜欢在构建过程中使用helper脚本，你可以
考虑用我们特有用的generate_test_runner.rb脚本。它会为你创建main函数以及所有的调用，
前提是你遵从建议的命名约定。这种情况下，你根本不需要将main函数包含进你的测试文件中。

当你完成上述步骤，你的测试文件应该看起来像这样：

#include "unity.h"
#include "file_to_test.h"

void setUp(void) {
    // 在这里配置东西
}

void tearDown(void) {
    // 在这里清理东西
}

void test_function_should_doBlahAndBlah(void) {
    //测试
}

void test_function_should_doAlsoDoBlah(void) {
    //更多测试
}

int main(void) {
    UNITY_BEGIN();
    RUN_TEST(test_function_should_doBlahAndBlah);
    RUN_TEST(test_function_should_doAlsoDoBlah);
    return UNITY_END();
}

最终，可能你需要更多的定制。这种情况下，你会想看看配置指南。尽管，这应该足够让你
行动了。

怎么构建和运行一个测试文件

单个最大的挑战是提取出一个新的单元测试框架，至少在像C或C++这样的语言中。这些语言
很擅长于让你"接近金属(注：貌似是接近本质的俚语)"(为什么这个句子中要用金属？说
"接近硅"不应该更加准确么？)。尽管这个特性通常是个好事情，但它会使得测试更具挑战。

你在工具链上有两个真的很好的选择。取决于你的学识，可能你会惊讶这两个选择都没在你
的硬件上运行单元测试。
这有许多原因，但这里是一个短的版本：

• 在硬件上，你有太多的约束(如处理能力、内存)，
• 在硬件上，你无法完全控制所有的寄存器
• 在硬件上，单元测试更加有挑战
• 单元测试不是系统测试。要区分开他们。

大部分开发者选择将单元测试作为本地应用程序(比如使用gcc或MSVC)或运行在模拟器上的应用程
序来开发，而不是在你的真正硬件上运行单元测试。这两个都是好选择。本地应用的优势是配置
起来更加快和简单。模拟器应用程序的优势是使用的是与你目标硬件相同的编译器。配置这两的
选项在配置指南中有探讨。

为了使任一选择工作，你也许需要对包含你寄存器集的文件做一些修改(之后会讨论)。

在两种情况下，一个测试的构建都要链接unity、测试文件以及被测试的C文件。这些文件创建了
一个可执行文件，这可执行文件可以当做那个模块的测试集来运行。然后，这个过程照搬到下一个
测试文件。拆分测试到独立的可执行文件的灵活性使得我们能更全面的对我们的系统进行单元测试
，并且所有测试代码都不在我们最终的产品代码中。

Find The Latest of This And More at ThrowTheSwitch.org

---

以下是中英对照版

---

Unity - Getting Started

Welcome

Congratulations. You’re now the proud owner of your very own pile of bits! What
are you going to do with all these ones and zeros? This document should be able
to help you decide just that.
恭喜。你现在是你那堆bit的光荣的主人了！你准备对你的那些1和0做些什么呢？这篇文档
应该能够帮助你决定这些。

Unity is a unit test framework. The goal has been to keep it small and
functional. The core Unity test framework is three files: a single C file and a
couple header files. These team up to provide functions and macros to make
testing easier.
Unity是一个单元测试框架。目标是精简而强大。Unity测试框架的内核是三个文件：单个C
文件和两个头文件。它们相互合作提供许多函数和宏以使得测试更顺滑。

Unity was designed to be cross-platform. It works hard to stick with C standards
while still providing support for the many embedded C compilers that bend the
rules. Unity has been used with many compilers, including GCC, IAR, Clang,
Green Hills, Microchip, and MS Visual Studio. It’s not much work to get it to
work with a new target.
Unity的设计是跨平台的。它尽可能地遵从C标准，同时提供对许多不守规矩的嵌入式C编译器
的支持。Unity已被用在许多编译器上，包括GCC、IAR、Clang、Green Hills、 Microchip和
MS Visual Studio。将其移植到一个新目标上不需要太多工作量。

Overview of the Documents

文档综述

Unity Assertions reference

断言参考文档

This document will guide you through all the assertion options provided by
Unity. This is going to be your unit testing bread and butter. You’ll spend more
time with assertions than any other part of Unity.
这篇文档将带你看遍Unity提供的所有断言选项。这是你单元测试的面包黄油。你将在断言上
花费比Unity其他部分更多的时间。

Unity Assertions Cheat Sheet

断言欺骗表

This document contains an abridged summary of the assertions described in the
previous document. It’s perfect for printing and referencing while you
familiarize yourself with Unity’s options.
这篇文档是之前那个文档中各种断言的一个删减的总结表。特别适合打印出来以备参考。

Unity Configuration Guide

配置向导

This document is the one to reference when you are going to use Unity with a new
target or compiler. It’ll guide you through the configuration options and will
help you customize your testing experience to meet your needs.
当你打算在一个新目标或编译器上使用Unity时，这篇文档是你要参考的。它会将你看遍配置
选项，帮助你定制你自己的测试环境以满足你的需求。

Unity Helper Scripts

脚本

This document describes the helper scripts that are available for simplifying
your testing workflow. It describes the collection of optional Ruby scripts
included in the auto directory of your Unity installation. Neither Ruby nor
these scripts are necessary for using Unity. They are provided as a convenience
for those who wish to use them.
这盘文档描述了helper脚本，helper脚本有助于简化你的测试工作流。它描述了在你的Unity
安装路径下auto文件夹内的那些可用的Ruby脚本。使用Unity并不需要用到Ruby以及这些脚本。
它们只是给想用的人提供一些便利而已。

Unity License

What’s an open source project without a license file? This brief document
describes the terms you’re agreeing to when you use this software. Basically, we
want it to be useful to you in whatever context you want to use it, but please
don’t blame us if you run into problems.
开源项目难道能没有license文件？这篇简短的文档描述了在你使用这个软件时应该同意的条
款。基本上，我们希望不管你想在什么上下文中使用它，它都能对你很有帮助，但是如果你
遇到了问题，请不要责备我们。

Overview of the Folders

文件夹综述

If you have obtained Unity through Github or something similar, you might be
surprised by just how much stuff you suddenly have staring you in the face.
Don’t worry, Unity itself is very small. The rest of it is just there to make
your life easier. You can ignore it or use it at your convenience. Here’s an
overview of everything in the project.
如果你是从Github或其他类似的地方获取Unity的，你很可能被眼前的一堆吓了一跳。
别担心，Unity本身十分的小。其他部分之所以在这只是为了让你的生活过的更好些。
你可以忽视它们或使用它们，全凭你自己做主。这里是工程中所有东西的综述。

• src - This is the code you care about! This folder contains a C file and two
  header files. These three files are Unity.

• docs - You’re reading this document, so it’s possible you have found your way
  into this folder already. This is where all the handy documentation can be
  found.

• examples - This contains a few examples of using Unity.

• extras - These are optional add ons to Unity that are not part of the core
  project. If you’ve reached us through James Grenning’s book, you’re going to
  want to look here.

• test - This is how Unity and its scripts are all tested. If you’re just using
  Unity, you’ll likely never need to go in here. If you are the lucky team member
  who gets to port Unity to a new toolchain, this is a good place to verify
  everything is configured properly.

• auto - Here you will find helpful Ruby scripts for simplifying your test
  workflow. They are purely optional and are not required to make use of Unity.

• src - 这是你关心的代码！这个文件夹包含一个C文件以及两个头文件。这三个文件 是 Unity。

• docs - 你正在读这个文档，所以可能你是自己进到这个文件夹中的。这里放着所有的文档。

• examples - 这里包含一些使用Unity的示例。

• extras - 这些是可选的Unity插件，它们不是内核工程的一部分。如果你是通过James Grenning的
  书找到我们的，你会想看看这里。

• test - 这里是Unity和它的所有脚本被测试的地方。如果你只是在用Unity，很可能你永远不需要
  看这个文件夹。如果你是团队中负责把Unity移植到新工具链的中奖者，这里可以帮助你验证所有东西
  都被合理地配置了。

• auto - 在这里你将发现一些有用的Ruby脚本，它们可以简化你的测试工作。他们完全只是可选的，
  不用它们照样可以使用Unity。

How to Create A Test File

怎么创建一个测试文件

Test files are C files. Most often you will create a single test file for each C
module that you want to test. The test file should include unity.h and the
header for your C module to be tested.
测试文件都是C文件。大部分情况下，你将为每个你想要测试的C模块创建一个测试文件。
测试文件应该include unity.h以及你要测试的C模块的头文件。

Next, a test file will include a setUp() and tearDown() function. The setUp
function can contain anything you would like to run before each test. The
tearDown function can contain anything you would like to run after each test.
Both functions accept no arguments and return nothing. You may leave either or
both of these blank if you have no need for them. If you’re using a compiler
that is configured to make these functions optional, you may leave them off
completely. Not sure? Give it a try. If you compiler complains that it can’t
find setUp or tearDown when it links, you’ll know you need to at least include
an empty function for these.
下一步，一个测试文件将包含一个setUp()以及tearDown()函数。setUp函数可以包含任何你
想要在每个测试之前运行的东西。tearDown函数可以包含任何你想要在每个测试之后运行的东西。
两个函数都不接受任何参数，也不返回东西。如果你在使用一个将这些函数配置为可选的编译器，
你也许可以不实现他们。不确定？试一试不就知道了。如果你的编译器抱怨说它在链接时找不到
setUp或tearDown，那你就知道你起码需要为它们创建一个空的函数了。

The majority of the file will be a series of test functions. Test functions
follow the convention of starting with the word “test_” or “spec_”. You don’t HAVE
to name them this way, but it makes it clear what functions are tests for other
developers. Also, the automated scripts that come with Unity or Ceedling will default
to looking for test functions to be prefixed this way. Test functions take no arguments
and return nothing. All test accounting is handled internally in Unity.
文件的主体将会是一系列的测试函数。测试函数遵从以下命名约定，以"test_"或"spec_"为开头。
不是必须按照这种方式命名它们，但是这样会使得其他开发者更容易看出哪些函数是测试。同样的，
Unity或Ceedling自带的自动化脚本将默认通过这种前缀的方式来寻找测试函数。测试函数都不接受
任何参数，也不返回东西。所有的测试计数是由Unity内部处理的。

Finally, at the bottom of your test file, you will write a main() function.
This function will call UNITY_BEGIN(), then RUN_TEST for each test, and
finally UNITY_END().This is what will actually trigger each of those test
functions to run, so it is important that each function gets its own RUN_TEST
call.
最终，在你的测试文件的最底下，你将写一个main()函数。这个函数将调用UNITY_BEGIN()，
然后为每个测试调用RUN_TEST，然后最终是UNITY_END()。这是实际上触发每个测试函数运行
的地方，所以重要的是，每个函数都要有它自己的RUN_TEST。

Remembering to add each test to the main function can get to be tedious. If you
enjoy using helper scripts in your build process, you might consider making use
of our handy generate_test_runner.rb script. This will create the main function
and all the calls for you, assuming that you have followed the suggested naming
conventions. In this case, there is no need for you to include the main function
in your test file at all.
把每个测试加进main函数的过程真是很无聊。如果你喜欢在构建过程中使用helper脚本，你可以
考虑用我们特有用的generate_test_runner.rb脚本。它会为你创建main函数以及所有的调用，
前提是你遵从建议的命名约定。这种情况下，你根本不需要将main函数包含进你的测试文件中。

When you’re done, your test file will look something like this:
当你完成上述步骤，你的测试文件应该看起来像这样：

#include "unity.h"
#include "file_to_test.h"

void setUp(void) {
    // set stuff up here
    // 在这里配置东西
}

void tearDown(void) {
    // clean stuff up here
    // 在这里清理东西
}

void test_function_should_doBlahAndBlah(void) {
    //test stuff
    //测试
}

void test_function_should_doAlsoDoBlah(void) {
    //more test stuff
    //更多测试
}

int main(void) {
    UNITY_BEGIN();
    RUN_TEST(test_function_should_doBlahAndBlah);
    RUN_TEST(test_function_should_doAlsoDoBlah);
    return UNITY_END();
}

It’s possible that you will need more customization than this, eventually.
For that sort of thing, you’re going to want to look at the configuration guide.
This should be enough to get you going, though.
最终，可能你需要更多的定制。这种情况下，你会想看看配置指南。尽管，这应该足够让你
行动了。

How to Build and Run A Test File

怎么构建和运行一个测试文件

This is the single biggest challenge to picking up a new unit testing framework,
at least in a language like C or C++. These languages are REALLY good at getting
you “close to the metal” (why is the phrase metal? Wouldn’t it be more accurate
to say “close to the silicon”?). While this feature is usually a good thing, it
can make testing more challenging.
单个最大的挑战是提取出一个新的单元测试框架，至少在像C或C++这样的语言中。这些语言
很擅长于让你"接近金属(注：貌似是接近本质的俚语)"(为什么这个句子中要用金属？说
"接近硅"不应该更加准确么？)。尽管这个特性通常是个好事情，但它会使得测试更具挑战。

You have two really good options for toolchains. Depending on where you’re
coming from, it might surprise you that neither of these options is running the
unit tests on your hardware.
There are many reasons for this, but here’s a short version:

• On hardware, you have too many constraints (processing power, memory, etc),
• On hardware, you don’t have complete control over all registers,
• On hardware, unit testing is more challenging,
• Unit testing isn’t System testing. Keep them separate.

你在工具链上有两个真的很好的选择。取决于你的学识，可能你会惊讶这两个选择都没在你
的硬件上运行单元测试。
这有许多原因，但这里是一个短的版本：

• 在硬件上，你有太多的约束(如处理能力、内存)，
• 在硬件上，你无法完全控制所有的寄存器
• 在硬件上，单元测试更加有挑战
• 单元测试不是系统测试。要区分开他们。

Instead of running your tests on your actual hardware, most developers choose to
develop them as native applications (using gcc or MSVC for example) or as
applications running on a simulator. Either is a good option. Native apps have
the advantages of being faster and easier to set up. Simulator apps have the
advantage of working with the same compiler as your target application. The
options for configuring these are discussed in the configuration guide.
大部分开发者选择将单元测试作为本地应用程序(比如使用gcc或MSVC)或运行在模拟器上的应用程
序来开发，而不是在你的真正硬件上运行单元测试。这两个都是好选择。本地应用的优势是配置
起来更加快和简单。模拟器应用程序的优势是使用的是与你目标硬件相同的编译器。配置这两的
选项在配置指南中有探讨。

To get either to work, you might need to make a few changes to the file
containing your register set (discussed later).
为了使任一选择工作，你也许需要对包含你寄存器集的文件做一些修改(之后会讨论)。

In either case, a test is built by linking unity, the test file, and the C
file(s) being tested. These files create an executable which can be run as the
test set for that module. Then, this process is repeated for the next test file.
This flexibility of separating tests into individual executables allows us to
much more thoroughly unit test our system and it keeps all the test code out of
our final release!
在两种情况下，一个测试的构建都要链接unity、测试文件以及被测试的C文件。这些文件创建了
一个可执行文件，这可执行文件可以当做那个模块的测试集来运行。然后，这个过程照搬到下一个
测试文件。拆分测试到独立的可执行文件的灵活性使得我们能更全面的对我们的系统进行单元测试
，并且所有测试代码都不在我们最终的产品代码中。

Find The Latest of This And More at ThrowTheSwitch.org