Home > The Unit Test Framework > User's guide >

Unit Test Framework: User's guide

Table of Contents

Usage variants
Static library
Dynamic library
Single header
External test runner
Supplied test runners
External test runner
Test module initialization
Test organization
Nullary function based test case
Manual registration
Automated registration
Unary function based test case
Test case template
Manual registration
Automated registration
Test suite
Manual registration
Automated registration
Master Test Suite
Expected failures specification
Generic model
Per test case
Test suite shared
Global fixture
Test Output
Test log
Logging floating point type numbers
Human readable format
XML based log output format
Compile time configuration
Test report output
Progress display
Runtime configuration
Run by name
Parameters reference

Introduction or what's your name?

Without further ado, let's define terms regularly used by the UTF.
在遇到更多麻煩之前,我們定義一些 UTF 經常使用的術語。

The test module

This is a single binary that performs the test. Physically a test module consists of one or more test source files, which can be built into an executable or a dynamic library. A test module that consists of a single test source file is called single-file test module. Otherwise it's called multi-file test module. Logically a test module consists of four parts: test setup (or test initialization), test body, test cleanup and test runner. The test runner part is optional. If a test module is built as an executable the test runner is built-in. If a test module is built as a dynamic library, it is run by an external test runner.
這是運行測試的單個二進制文件。從物理上講測試模塊包含一個或多個測試源文件,並被生成為一個可執行文件或動態庫。 只包含單個測試源文件的測試模塊被稱為單文件測試模塊。否則被稱為多文件測試模塊。 從邏輯上講,測試模塊包含四個部分:測試安裝(或測試初始化),測試主體測試清理測試運行器。 測試運行器部分是可選的。如果測試模塊被生成為可執行的,測試運行器是內置的。 如果測試模塊被生成為動態庫,它就被一個外部的測試運行器運行。

The test body

This is the part of a test module that actually performs the test. Logically test body is a collection of test assertions wrapped in test cases, which are organized in a test tree .

The test tree

This is a hierarchical structure of test suites (non-leaf nodes) and test cases (leaf nodes).
測試套件 (非葉節點) 和測試用例 (葉節點) 的層次結構。

The test unit

This is a collective name when referred to either test suite or test case

Test assertion

This is a single binary condition (binary in a sense that is has two outcomes: pass and fail) checked by a test module.
由測試模塊檢查的單個二元條件 (這裡的二元指有兩種可能:通過或失敗)。

There are different schools of thought on how many test assertions a test case should consist of. Two polar positions are the one advocated by TDD followers - one assertion per test case; and opposite of this - all test assertions within single test case - advocated by those only interested in the first error in a test module. The UTF supports both approaches.
對於測試用例應該有多少測試斷言有不同的學派。有兩種極端的情況:TDD 支持者提倡的 - 每個測試用例一個測試斷言; 相反的是 - 所有測試判斷放在單個測試用例中 - 那些只關注於測試模塊第一個錯誤的人提倡。

The test case

This is an independently monitored function within a test module that consists of one or more test assertions. The term "independently monitored" in the definition above is used to emphasize the fact, that all test cases are monitored independently. An uncaught exception or other normal test case execution termination doesn't cause the testing to cease. Instead the error is caught by the test case execution monitor, reported by the UTF and testing proceeds to the next test case. Later on you are going to see that this is on of the primary reasons to prefer multiple small test cases to a single big test function.
測試模塊內由一個或多個測試斷言組成的獨立的被監控的函數。上面定義中術語 "獨立被監控" 是用來強調這樣的事實, 所有的測試用例都被彼此獨立地監控。未捕獲的異常或其它正常的測試用例執行中止都不會中斷其它的測試用例。 相反,錯誤被測試用例執行監控器捕獲,由 UTF 報告,並且繼續進行下面的測試用例。 接下來你會看到,這是使用多個小測試用例而不是單個大的測試函數的一個主要原因。

The test suite

This is a container for one or more test cases. The test suite gives you an ability to group test cases into a single referable entity. There are various reasons why you may opt to do so, including:
一個或多個測試用例的容器。測試套件能夠將多個測試用例組合為單個可引用的實體。 有很多原因使用它,包括:

  • To group test cases per subsystems of the unit being tested.
  • To share test case setup/cleanup code.
    共享測試用例的安裝 / 清理代碼
  • To run selected group of test cases only.
  • To see test report split by groups of test cases
  • To skip groups of test cases based on the result of another test unit in a test tree.

A test suite can also contain other test suites, thus allowing a hierarchical test tree structure to be formed. The UTF requires the test tree to contain at least one test suite with at least one test case. The top level test suite - root node of the test tree - is called the master test suite.
測試套件也能夠包含其它測試套件,也就是允許組織成分層的測試樹結構。 UTF 要求每個測試樹必須包含至少一個測試套件。 頂層測試套件 - 測試樹的根節點 - 被稱為主測試套件。

The test setup

This is the part of a test module that is responsible for the test preparation. It includes the following operations that take place prior to a start of the test:

  • The UTF initialization
    UTF 初始化
  • Test tree construction
  • Global test module setup code

Per test case" setup code, invoked for every test case it's assigned to, is also attributed to the test initialization, even though it's executed as a part of the test case.
每個測試用例的 "安裝" 代碼,由每個相關的測試用例調用,同樣歸為測試初始化,雖然它是作為測試用例的一部分被執行的。

The test cleanup

This is the part of test module that is responsible for cleanup operations.

The test fixture

Matching setup and cleanup operations are frequently united into a single entity called test fixture.

The test runner

This is an "executive manager" that runs the show. The test runner's functionality should include the following interfaces and operations:
這是運行測試的 "運行管理器"。測試運行器的功能包括下面的接口和操作:

  • Entry point to a test module. This is usually either the function main() itself or single function that can be invoked from it to start testing.
    測試模塊的入口點。通常是 main() 函數或者是啟動測試的單個函數。
  • Initialize the UTF based on runtime parameters
    根據運行時參數初始化 UTF
  • Select an output media for the test log and the test results report
  • Select test cases to execute based on runtime parameters
  • Execute all or selected test cases
  • Produce the test results report
  • Generate a test module result code.

An advanced test runner may provide additional features, including interactive GUI interfaces, test coverage and profiling support.
高級的測試運行器還會提供額外的特性,包括交互的 GUI 接口,測試覆蓋率和剖面支持。

The test log

This is the record of all events that occur during the testing.

The test results report

This is the report produced by the UTF after the testing is completed, that indicates which test cases/test suites passed and which failed.
測試完成後由 UTF 生成的報告,簡要說明哪些測試用例 / 測試套件成功,哪些失敗。