BugreportCollector

public class BugreportCollector
extends Object implements ITestInvocationListener

java.lang.Object
↳	com.android.tradefed.result.BugreportCollector

---

這個 ITestInvocationListener 會在可設定的事件發生時收集錯誤報告，並在收集每份錯誤報告後，對子項呼叫 ITestInvocationListener.testLog。

行為：(FIXME：完成此步驟)

• 在每個測試案例失敗後擷取畫面 (如有)
• 在每個測試案例後擷取
• 在每個失敗的測試案例後擷取畫面
• 擷取

摘要

巢狀類別
class	BugreportCollector.Predicate 完整述詞，說明何時要擷取錯誤報告。
interface	BugreportCollector.SubPredicate

欄位
public static final BugreportCollector.Predicate	AFTER_FAILED_TESTCASES 預先定義的述詞，會在每個測試案例失敗後觸發
public static final BugreportCollector.Predicate	AT_START 預先定義的述詞，會在第一次叫用開始時觸發

公用建構函式
BugreportCollector(ITestInvocationListener listener, ITestDevice testDevice)

公用方法
void	addPredicate(BugreportCollector.Predicate p)
void	blockUntilIdle() Block until the collector is not collecting any bugreports.
TestSummary	getSummary() 允許 InvocationListener 傳回摘要。
void	invocationEnded(long elapsedTime) 回報是否因某種錯誤狀況而終止呼叫 (無論是否成功)。
void	invocationFailed(Throwable cause) Reports an incomplete invocation due to some error condition.
void	invocationStarted(IInvocationContext context) Reports the start of the test invocation.
void	setAsynchronous(boolean asynchronous) 設定錯誤報告收集作業是否應在不同執行緒中收集錯誤報告 (asynchronous = true)，或封鎖呼叫端，直到擷取錯誤報告為止 (asynchronous = false)。
void	setDescriptiveName(String name) 設定記錄錯誤報告時要使用的描述性名稱。
void	setDeviceWaitTime(int waitTime) 設定等待裝置上線的時間 (秒)，之後我們會嘗試擷取錯誤報告。
void	testAssumptionFailure(TestDescription test, String trace) 當原子測試標記假設為 false 的條件時，系統會呼叫這個函式
void	testEnded(TestDescription test, HashMap<String, MetricMeasurement.Metric> testMetrics) 回報個別測試案例的執行結束時間。
void	testFailed(TestDescription test, String trace) 回報個別測試案例的失敗情形。
void	testIgnored(TestDescription test) 當測試不會執行時呼叫，通常是因為測試方法以 org.junit.Ignore 註解標註。
void	testLog(String dataName, LogDataType dataType, InputStreamSource dataStream) 提供測試呼叫的相關記錄或偵錯資料。
void	testRunEnded(long elapsedTime, HashMap<String, MetricMeasurement.Metric> runMetrics) Reports end of test run.
void	testRunFailed(String errorMessage) 發生嚴重錯誤，因此無法完成報表測試執行。
void	testRunStarted(String runName, int testCount) 回報測試執行的開始。
void	testRunStopped(long elapsedTime) 由於使用者要求，報表測試執行作業在完成前停止。
void	testStarted(TestDescription test) 回報個別測試案例的開始時間。

欄位

AFTER_FAILED_TESTCASES

public static final BugreportCollector.Predicate AFTER_FAILED_TESTCASES

預先定義的述詞，會在每個測試案例失敗後觸發

AT_START

public static final BugreportCollector.Predicate AT_START

預先定義的述詞，會在第一次叫用開始時觸發

公用建構函式

BugreportCollector

public BugreportCollector (ITestInvocationListener listener, 
                ITestDevice testDevice)

參數
listener	ITestInvocationListener
testDevice	ITestDevice

公用方法

addPredicate

public void addPredicate (BugreportCollector.Predicate p)

參數
p	BugreportCollector.Predicate

blockUntilIdle

public void blockUntilIdle ()

封鎖，直到收集器未收集任何錯誤報告為止。如果收集器未主動收集錯誤報告，請立即傳回

getSummary

public TestSummary getSummary ()

允許 InvocationListener 傳回摘要。

傳回
TestSummary	總結執行作業的 TestSummary，或空值

invocationEnded

public void invocationEnded (long elapsedTime)

回報是否因某種錯誤情況而終止呼叫 (無論是否成功)。

TradeFederation 架構會自動呼叫。

參數
elapsedTime	long：以毫秒為單位的呼叫經過時間

invocationFailed

public void invocationFailed (Throwable cause)

由於發生某些錯誤情況，因此回報不完整的叫用。

TradeFederation 架構會自動呼叫。

參數
cause	Throwable：Throwable 失敗的原因

invocationStarted

public void invocationStarted (IInvocationContext context)

回報測試呼叫的開始時間。

TradeFederation 架構會自動呼叫這個方法。檢舉者需要覆寫這個方法，才能支援多部裝置回報。

參數
context	IInvocationContext：叫用相關資訊

setAsynchronous

public void setAsynchronous (boolean asynchronous)

設定錯誤報告收集作業是否應在不同執行緒中收集錯誤報告 (asynchronous = true)，或封鎖呼叫端，直到擷取錯誤報告為止 (asynchronous = false)。

參數
asynchronous	boolean

setDescriptiveName

public void setDescriptiveName (String name)

設定錄製錯誤報告時要使用的描述性名稱。如果 null，BugreportCollector 會改為序列化導致收集錯誤報告的事件名稱。

參數
name	String

setDeviceWaitTime

public void setDeviceWaitTime (int waitTime)

設定等待裝置上線的時間 (秒)，之後我們才會嘗試擷取錯誤報告。如果為負數，系統就不會執行檢查。系統會記錄並忽略檢查期間遇到的任何 DeviceNotAvailableException 。

參數
waitTime	int

testAssumptionFailure

public void testAssumptionFailure (TestDescription test, 
                String trace)

當原子測試標記假設為 false 的條件時呼叫

參數
test	TestDescription：識別測試
trace	String：失敗的堆疊追蹤

testEnded

public void testEnded (TestDescription test, 
                HashMap<String, MetricMeasurement.Metric> testMetrics)

回報個別測試案例的執行結束時間。

如果未叫用 testFailed(TestDescription, FailureDescription)，這項測試就會通過。也會傳回測試案例執行期間可能發出的任何鍵/值指標。

參數
test	TestDescription：識別測試
testMetrics	HashMap：發出的指標 Map

testFailed

public void testFailed (TestDescription test, 
                String trace)

回報個別測試案例的失敗情形。

會在 testStarted 和 testEnded 之間呼叫。

參數
test	TestDescription：識別測試
trace	String：失敗的堆疊追蹤

testIgnored

public void testIgnored (TestDescription test)

當測試不會執行時呼叫，通常是因為測試方法以 org.junit.Ignore 註解標註。

參數
test	TestDescription：識別測試

testLog

public void testLog (String dataName, 
                LogDataType dataType, 
                InputStreamSource dataStream)

提供測試呼叫的相關記錄或偵錯資料。

必須在 ERROR(ITestInvocationListener.invocationFailed(Throwable)/ITestInvocationListener#invocationFailed(java.lang.Throwable) ITestInvocationListener.invocationFailed(Throwable)) 或 ERROR(/ITestInvocationListener#invocationEnded(long)) 之前呼叫

TradeFederation 架構會自動呼叫這個方法，提供主機記錄和裝置 logcat (如適用)。

參數
dataName	String：資料的String說明名稱，例如「device_logcat」。注意：dataName 在每次呼叫時可能不具唯一性，也就是說，實作者必須能夠處理具有相同 dataName 的多項呼叫。
dataType	LogDataType：資料的 LogDataType
dataStream	InputStreamSource：資料的 InputStreamSource。實作者應呼叫 createInputStream 開始讀取資料，並確保在完成時關閉產生的 InputStream。呼叫端應確保資料來源持續存在且可存取，直到 testLog 方法完成為止。

testRunEnded

public void testRunEnded (long elapsedTime, 
                HashMap<String, MetricMeasurement.Metric> runMetrics)

測試執行結束時會回報。FIXME：我們無法使用不同型別的兩個 Map<> 介面，因此必須在此使用 HashMap。

參數
elapsedTime	long：裝置回報的經過時間 (以毫秒為單位)
runMetrics	HashMap：在測試執行結束時，使用 Metric 報告的鍵/值組合。

testRunFailed

public void testRunFailed (String errorMessage)

發生嚴重錯誤，因此無法完成報表測試執行作業。

參數
errorMessage	String：String，說明執行失敗的原因。

testRunStarted

public void testRunStarted (String runName, 
                int testCount)

回報測試執行的開始時間。

參數
runName	String：測試執行名稱
testCount	int：測試執行作業中的測試總數

testRunStopped

public void testRunStopped (long elapsedTime)

由於使用者要求，報表測試執行作業在完成前停止。

TODO：目前未使用，考慮移除

參數
elapsedTime	long：裝置回報的經過時間 (以毫秒為單位)

testStarted

public void testStarted (TestDescription test)

回報個別測試案例的開始時間。舊版介面，建議盡可能使用 testStarted(TestDescription)。

參數
test	TestDescription：識別測試