diff --git a/docs/HowToUse_ch.md b/docs/HowToUse_ch.md new file mode 100644 index 0000000..f7c4c35 --- /dev/null +++ b/docs/HowToUse_ch.md @@ -0,0 +1,284 @@ +這份文件用於說明怎麼用Skypat來測試你的程式與評估它的效能。 + +### 介紹 + +SkyPat 用於 C++ 效能分析與提供一個在Android與Linux平台上效能評估與測試框架。 +這個專案主要源自 Google Test 的觀念,並新增效能測試的框架 + +有了 SkyPat ,想要分析程式的程式設計者只要透過 SkyPat API 就可以寫自己的測試,並且同時分析程式表現的正確性及效能。 + +接下來為 SkyPat 使用上的範例。 + +### 基礎觀念 + +基本的 SkyPat 操作說明 + +1. 使用 _ASSERT_, _EXPECT_, and _PERFORM_ 巨集來撰寫測試 +2. 使用 SkyPat 的動態函式庫以編譯你的測試程式 +3. 最後執行便可獲得其正確性與效能的報告 + +與其他的測試函式庫(像 Google Test)一樣,Skypat 提供不少巨集以整合你的測試。下個部份將會介紹各個巨集以及解釋該如何使用這些巨集 + +### 巨集 + +SkyPat 總共有三類巨集,分別是 _ASSERT_,_EXPECT_,跟 _PERFORM_。 +_ASSERT_,_EXPECT_ 提供在條件判斷上的 assertion(中譯為「斷言」),而 _PERFORM_ 可以對一個程式段落做效能分析。_ASSERT_ 與 _EXPECT_ 的差別僅在於程式遇到錯誤是否會中斷執行。 + +_ASSERT_ 是針對測試中嚴重的錯誤處理,如果 _ASSERT_ 條件判斷失敗,整個測試案例將會中斷並馬上離開。 + +_EXPECT_ 則是負責那些不是那麼嚴重,尚可容忍的錯誤。當 _EXPECT_ 的條件失敗時,程式並不會因此中斷,Skypat 會把錯誤訊息記錄下來並繼續執行,並且此時整個測試案例還不算是失敗 + +_PERFORM_ 負責評估程式碼的效能,測試一段程式碼內的性能表現 + +下個部份將提供你怎麼使用這些巨集的範例程式,並解釋程式輸出的意義 + +### 範例 + +以下所有範例程式碼也存在於 SkyPat 的程式中, _${PAT_SRC}/examples_ + +#### 引入 SkyPat 函式庫 + +讓我們從這個做常用的巨集 _ASSERT_ 開始。 + +所有的巨集以及定義都位於 + +舉個例子,在 `assertion/main.cpp`,它包含 + + #include "pat/pat.h" + +#### 透過 _PAT\_F_ 宣告測試 + +_PAT\_F_ 巨集用以宣告一個測試 +該測試需要兩個參數,「測試案例的名字」與「測試函式名字」 + +在 SkyPat 架構邏輯中,整個測試流程會被分成不同的測試案例,而每個測試案例又由測試函式組成。 + +以下是一個宣告測試函式的基本範例 + + PAT_F(AircraftCase, take_off_test) + { + // Your Test Code + } + PAT_F(AircraftCase, landing_test) + { + // Your Test Code + } + +這個範例定義了一個名叫 _AircraftCase_ 的測試案例,其中由兩個測試函式,_take\_off\_test_ 與 _landing\_test_ 組成 + +這就是 SkyPat 測試邏輯的架構 +建議您可以將邏輯上相關連的測試函式放入同一個測試案例中 + +#### 撰寫一個測試函式 + +藉由撰寫測試函式,使用者可以評估該程式的效能與可信度 +可信度的評估可透過在一段程式中使用 _ASSERT_ 或 _EXPECT_ +效能評估則是使用 _PERFORM_ 巨集 +下個部份將會解釋: + * 該如何插入一個致命的條件判斷(fatal condition),用以偵測嚴重的錯誤 + * 該如何插入多個致命的條件判斷 + * 該如何插入不致命的條件判斷,用以處理不嚴重錯誤 + * 評估效能 + +##### 插入一個致命的條件判斷 +下列案例展示你該如何使用 _ASSERT\_TRUE_ 與 _ASSERT\_FALSE_ 以撰寫測試函式 + +這是一個 _ASSERT\_TRUE_ : + + PAT_F(SeriesCase, fibonacci_test) + { + int result = 0; + + ASSERT_TRUE(0 != fibonacci(10)); + } + +_ASSERT_ 是一個類似函式的巨集,透過使用假設(assertion)來測試一個類別(class)或函式(function) 的行為 +如上所述,_ASSERT_總共有兩種, _ASSERT\_TRUE_ 與 _ASSERT\_FALSE_ + +_ASSERT\_TRUE_ 只會在條件判斷是 TRUE 的情況下通過,而在這個例子裡,條件判斷為 "0 != fibonacci(10)" 很明顯為 TRUE,因此成功通過此假設 +反之,若 _ASSERT\_TRUE_ 條件判斷失敗,此測試案例立即中斷並且離開 + +這裡是一個 FALSE 的條件判斷 + +Here is an example to show a false condition: + + PAT_F(SeriesCase, factorial_test_fail) + { + ASSERT_TRUE(360 == factorial(5)); + + cout<<"end of the test"< + +For example, in `assertion/main.cpp`, it includes: + + #include "pat/pat.h" + +#### Declare A Test Function via _PAT_F_ +_PAT_F_ macro declare a test. +It has two parameters: test case's name and test function's name. +In **SkyPat**, test logic is grouped into `test cases`. Every test case has a bunch of `test functions`. Here is an example to declare a test function. + + PAT_F(AircraftCase, take_off_test) + { + // Your Test Code + } + PAT_F(AircraftCase, landing_test) + { + // Your Test Code + } + +This example defines a test case _AircraftCase_ who has two test functions _take_off_test_ and _landing_test_. +This is how does the **SkyPat** organize the test codes. +You should put logically related tests into the same test case. + +#### Write A Test Function +By writing test functions, users can evaluate performance and reliability. +For reliability, users can assert fatal or non-fatal conditions in a block of code; For performance, users can evaluate performance by using pat PERFORM macros. +The following examples explains: + * How to assert one fatal condition + * How to assert multiple fatal conditions + * How to assert non-fatal conditions + * Evaluate performance + +##### Assert one fatal condition +This example shows you how to use _ASSERT\_TRUE_ and _ASSERT\_FALSE_ to write a test function. + +Here is an example of _ASSERT\_TRUE_: + + PAT_F(SeriesCase, fibonacci_test) + { + int result = 0; + + ASSERT_TRUE(0 != fibonacci(10)); + } + + +_ASSERT_ is a macro resembling function calls. You test a class or a function by making assertions about its behavior. There are two kinds of _ASSERT_ macros, _ASSERT\_TRUE_ and _ASSERT\_FALSE_. + +First of all, _ASSERT\_TRUE_ means that it will PASS only if the condition is TRUE. In this case, our condition is `0 != fibonacci(10)` that is obviously TRUE. So this test is executed successfully. + +If the condition of _ASSERT\_TRUE_ fails, the test will stop and exit the test immediately. + +Here is an example to show a false condition: + + PAT_F(SeriesCase, factorial_test_fail) + { + ASSERT_TRUE(360 == factorial(5)); + + cout<<"end of the test"<