Home > The Unit Test Framework > User's guide > Test module initialization
PrevNext

Test module initialization or ready, set

There are two tasks that you may need to perform before actual testing can start:
在開始真正的測試之前你有兩件任務要做:

The function dedicated for this purpose is called the test module initialization function. Alternatively you can employ global fixtures, covered in details, including differences in two approaches, in the section called 「Fixtures」.
用於這個目的的函數被稱為測試模塊初始化函數。 或者你可以使用全局的夾具,兩者之間不同的細節在 「Fixture」 部分

The UTF requires you to implement the test module initialization function. The test runner supplied with the static library or single-header variants of the UTF requires the specific function specification. The test runner supplied with the dynamic library variant of the UTF requires the specific initialization function signature only.
UTF 需要你實現測試模塊初始化函數。 UTF 靜態庫或單頭文件用法中提供的測試運行器需要指定特定簽名的函數。 UTF 動態庫用法提供的測試運行器只需要特定初始化函數的簽名。(???)

For many test modules you don't need to do any custom initialization and test tree construction is automated. In this case you don't really need the initialization function and the UTF provides a way to automatically generate an empty one for you.
對於很多測試模塊來說,並不需要自定義初始化,測試樹的構造也是自動完成的。 在這種情況下你並不真的需要初始化函數,並且 UTF 提供了自動生成空初始化函數的能力。

Original design of the UTF supported the manual test tree construction only. Later versions introduced the automated registration of test units. In later versions of the UTF the original initialization function specification became inconvenient and unnecessary unsafe. So the alternative initialization function specification was introduced. This change is not backward compatible. The test runners supplied with the static library and single-header variants of the UTF by default still require original initialization function specification, but support compilation flags that switch to the alternative one. The test runner supplied with dynamic library variant of the UTF requires new specification and doesn't support original one. The plan is to deprecate the original initialization function specification in one of the future releases and ultimately to stop supporting it.
UTF 的最初設計只支持手動構造測試樹。其後的版本引入了測試用例的自動註冊。 在 UTF 的後來版本中,最初的初始化函數定義變得不方便、不必要、不安全了。 所以引入了後備的初始化函數定義。這個變化不是後向兼容的。 靜態庫和單頭文件用法中提供的測試運行器仍然默認使用原先的初始化函數定義,但支持通過編譯標籤選擇後備函數。 動態庫用法提供的測試運行器需要新的定義,不支持原先的。 在將來的某個版本將廢棄到最初的初始化函數定義,並最終停止支持。

The initialization function invocation is monitored by the UTF the same way as all the test cases. An unexpected exception or system error detected during initialization function invocation is treated as initialization error and is reported as such.
就像測試用例一樣,初始化函數同樣被 UTF 監控調用。 在初始化函數調用期間檢查到的未預期的異常或系統錯誤被當作初始化錯誤對待並報告。

Original initialization function signature and name

The original design of the UTF initialization requires you to implement the function with the following specification:
UTF 最初的設計中需要你實現如下簽名的函數:

boost::unit_test::test_suite* init_unit_test_suite( int argc, char* argv[] );

In original design of the UTF this function was intended to initialize and return a master test suite. The null value was considered an initialization error. The current design of the UTF maintains master test suite instance internally and does not treat the null result value as an initialization error. In fact it's recommended to return null value always and register test units in the master test suite using the regular test suite add interface. The only way to indicate an initialization error is to throw the boost::unit_test::framework::setup_error exception.
UTF 的最初設計中,這個函數需要進行初始化並返回主測試套件。 空值被認為初始化錯誤。UTF 現在的設計在內部維護主測試套件, 並且不再認為空返回值是初始化錯誤。 事實上,現在總是推薦返回空值,並使用常用的測試套件添加接口來將測試套件註冊到主測試套件中。 表明初始化錯誤的惟一方法是拋出 boost::unit_test::framework::setup_error 異常。

The initialization function parameters argc, argv provide the command line arguments specified during test module invocation. It's guarantied that any framework-specific command line arguments are excluded. To be consisted with the alternative initialization function specification it's recommended though to access the command line arguments using the master test suite interface.
初始化函數參數 argc、argv 提供了在調用測試模塊時定義的命令行參數。 框架相關的命令已經被排除。 現在推薦使用主測試套件接口取得命令行參數,這樣可以和備選的初始化函數定義保持一致。

Alternative initialization function signature and name

The alternative design of the UTF initialization requires you to implement a function with the following specification:
UTF 的初始化備選設計需要你實現如下簽名的函數:

bool init_unit_test();

The result value of this function indicates whether or not initialization was successful. To register test units in a master test suite use the test suite add interface. To access command line arguments use the master test suite interface. It's guarantied that any framework-specific command line arguments are excluded.
返回值說明初始化成功與否。要將測試單元註冊到主測試套件中,使用測試套件添加接口。 使用主測試套件接口取得命令行參數。任何與框架有關的命令行參數都已經被排除了。

Initialization function signature access

The test runner interface needs to refer to the initialization function signature. The UTF provides the typedef that resolves to proper signature in all configurations:
測試運行器接口需要引用初始化函數簽名。UTF 提供了如下的 typedef 來確定在所有配置中的合適簽名:

namespace boost {
namespace unit_test {
#ifdef BOOST_TEST_ALTERNATIVE_INIT_API
typedef bool        (*init_unit_test_func)();
#else
typedef test_suite* (*init_unit_test_func)( int, char* [] );
#endif
}
}
Automated generation of the test module initialization function

To automatically generate an empty test module initialization function you need to define BOOST_TEST_MAIN before including the boost/test/unit_test.hpp header. The value of this define is ignored. Alternatively you can define the macro BOOST_TEST_MODULE to be equal to any string (not necessarily in quotes). This macro causes the same result as BOOST_TEST_MAIN, and in addition the macro value becomes the name of the master test suite.
為了自動生成空的測試模塊初始化函數,需要在包含 boost/test/unit_test.hpp 頭文件之前定義 BOOST_TEST_MAIN。定義的值將被忽略。 或者可以定義宏 BOOST_TEST_MODULE 為某個字符串 (不需要引號)。 這個宏可以造成和 BOOST_TEST_MAIN 相同的結果, 另外宏的值將作為主測試套件的名稱。

[Important] Important

For a test module consisting of multiple source files you have to define these flags in a single test file only. Otherwise you end up with multiple instances of the initialization function.
對於包含多個源文件的測試模塊,只能在一個測試文件中定義這些標籤。 否則你會由於多個初始化函數的實例而不能繼續。


PrevUpHomeNext