自 2025 年 3 月 27 日起，我們建議您使用 android-latest-release 而非 aosp-main 建構及貢獻 AOSP。詳情請參閱「Android 開放原始碼計畫變更」。

本頁面由 Cloud Translation API 翻譯而成。

CollectingTestListener

public class CollectingTestListener
extends Object implements IDisableable, ILogSaverListener, ITestInvocationListener

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

已知的直接子類別

JsonHttpTestResultReporter、LUCIResultReporter、MetricsXMLResultReporter、ModuleListener、ReportPassedTests、ResultAggregator、ShardListener、SuiteResultReporter、XmlResultReporter

JsonHttpTestResultReporter	結果回報器，可將測試指標結果和分支、裝置資訊編碼為 JSON，並 POST 到 HTTP 服務端點
LUCIResultReporter	結果回報工具，可將 ResultDB 和 LUCI 測試結果儲存為 JSON 格式 (go/result-sink)，並在控制台中記錄檔案位置。
MetricsXMLResultReporter	在測試的 invocationEnded 階段，MetricsXMLResultReporter 會將測試指標和執行指標寫入 metrics-folder 參數指定的資料夾中的 XML 檔案。
ModuleListener	附加至每個模組的每個 `IRemoteTest` 的監聽器，用於收集結果清單。
ReportPassedTests	在檔案中回報可排除通過測試的篩選器。
ResultAggregator	特殊轉送器，可根據採取的重試策略，在需要時彙整結果。
ShardListener	`ITestInvocationListener`：從叫用分片收集結果 (又稱「叫用分割」，可在多個資源上平行執行)，並將結果轉送至其他接聽程式。
SuiteResultReporter	收集整個套件呼叫的測試結果，並輸出最終結果。
XmlResultReporter	以符合 Ant 的 XMLJUnitResultFormatter 格式，將 JUnit 結果寫入 XML 檔案。

已知間接子類別

FormattedGeneratorReporter、XmlFormattedGeneratorReporter

FormattedGeneratorReporter	可產生特定格式報表的 Reporter。
XmlFormattedGeneratorReporter	實作 `FormattedGeneratorReporter`，將套件結果格式化為 XML 格式。

ITestInvocationListener，用於收集所有測試結果。

雖然這個物件中使用的資料結構是執行緒安全，但 ITestInvocationListener 回呼必須依正確順序呼叫。

摘要

公用建構函式
`CollectingTestListener()`

公用方法
`IBuildInfo`	`getBuildInfo()` 這個方法已淘汰。 `IBuildInfo`。 `getInvocationContext()`
`TestRunResult`	`getCurrentRunResults()` 取得目前測試執行的結果。
`int`	`getExpectedTests()` 傳回預期測試次數。
`IInvocationContext`	`getInvocationContext()` 傳回透過 `invocationStarted(com.android.tradefed.invoker.IInvocationContext)` 回報的叫用內容。
	`getMergedTestRunResults()` 傳回所有嘗試中所有執行的合併結果集合。
`IInvocationContext`	`getModuleContextForRunResult(String testRunName)` 傳回與結果相關聯的模組 `IInvocationContext`。
`MultiMap<String, LogFile>`	`getModuleLogFiles()` 傳回地圖副本，內含與模組相關聯的所有記錄檔案
`MultiMap<String, LogFile>`	`getNonAssociatedLogFiles()` 傳回地圖副本，其中包含所有未與測試執行或模組建立關聯的記錄檔案。
`int`	`getNumAllFailedTestRuns()` 傳回處於失敗狀態的測試執行總數
`int`	`getNumAllFailedTests()` 傳回處於失敗狀態的測試總數 (僅限失敗，假設失敗不會計入)。
`int`	`getNumTestsInState(TestStatus status)` 傳回這項執行作業中處於指定狀態的測試數量。
`int`	`getNumTestsInState(TestResult.TestStatus ddmlibStatus)` 如要與舊版狀態類型相容
`int`	`getNumTotalTests()` 傳回所有執行作業的完整測試總數。
`IBuildInfo`	`getPrimaryBuildInfo()` 傳回透過 `invocationStarted(com.android.tradefed.invoker.IInvocationContext)` 回報的主要建構資訊。
	`getRunResults()` 這個方法已淘汰。使用 `getMergedTestRunResults()`
`TestRunResult`	`getTestRunAtAttempt(String testRunName, int attempt)` 傳回單一嘗試的 `TestRunResult`。
`int`	`getTestRunAttemptCount(String testRunName)` 傳回指定測試執行名稱的嘗試次數。
	`getTestRunAttempts(String testRunName)` 取得指定測試執行的 `TestRunResult` 所有嘗試。
	`getTestRunForAttempts(int attempt)` 取得特定嘗試的所有結果。
	`getTestRunNames()` 傳回所有測試執行的所有名稱。
`boolean`	`hasFailedTests()` 傳回叫用是否發生任何失敗或假設失敗的測試。
`boolean`	`hasTestRunResultsForName(String testRunName)` 傳回指定測試執行名稱是否有任何結果。
`void`	`invocationEnded(long elapsedTime)` 回報是否因成功或發生錯誤而終止呼叫。
`void`	`invocationFailed(Throwable cause)` Reports an incomplete invocation due to some error condition.
`void`	`invocationSkipped(SkipReason reason)` 將叫用作業回報為已略過
`void`	`invocationStarted(IInvocationContext context)` 回報測試呼叫的開始時間。
`boolean`	`isDisabled()` 如果整個物件都已停用 (略過設定和終止)，則傳回 True。
`void`	`logAssociation(String dataName, LogFile logFile)` 在某些情況下，記錄必須與測試案例密切相關，但無法在直接 `testLogSaved(String, com.android.tradefed.result.LogDataType, com.android.tradefed.result.InputStreamSource, com.android.tradefed.result.LogFile)` 回呼中執行此操作。
`void`	`setBuildInfo(IBuildInfo buildInfo)` 這個方法已淘汰。不再是測試的必要條件。
`void`	`setDisable(boolean isDisabled)` 設定是否應停用物件。
`void`	`setMergeStrategy(MergeStrategy strategy)` 設定合併結果時要使用的 `MergeStrategy`。
`void`	`testAssumptionFailure(TestDescription test, String trace)` 當原子測試標記假設條件為 false 時，系統會呼叫這個函式。
`void`	`testAssumptionFailure(TestDescription test, FailureDescription failure)` 當原子測試標記假設條件為 false 時，系統會呼叫這個函式。
`void`	`testEnded(TestDescription test, long endTime, testMetrics)` `ERROR(/#testEnded(com.android.tradefed.result.TestDescription,Map))` 的替代方案，可直接指定結束時間。
`void`	`testEnded(TestDescription test, testMetrics)` 回報個別測試案例的執行結束時間。
`void`	`testFailed(TestDescription test, FailureDescription failure)` 回報個別測試案例的失敗情形。
`void`	`testFailed(TestDescription test, String trace)` 回報個別測試案例的失敗情形。
`void`	`testIgnored(TestDescription test)` Called when a test will not be run, generally because a test method is annotated with org.junit.Ignore.
`void`	`testModuleEnded()` 回報模組執行作業的結束時間。
`void`	`testModuleStarted(IInvocationContext moduleContext)` 回報模組的執行開始時間。
`void`	`testRunEnded(long elapsedTime, runMetrics)` Reports end of test run.
`void`	`testRunFailed(FailureDescription failure)` 由於 `FailureDescription` 所述的失敗情形，報表測試執行作業無法完成。
`void`	`testRunFailed(String errorMessage)` 由於發生嚴重錯誤，報表測試執行作業無法完成。
`void`	`testRunStarted(String name, int numTests, int attemptNumber)` 回報測試執行的開始時間。
`void`	`testRunStarted(String name, int numTests)` 回報測試執行的開始時間。
`void`	`testRunStarted(String name, int numTests, int attemptNumber, long startTime)` 回報測試執行的開始時間。
`void`	`testRunStopped(long elapsedTime)` 由於使用者要求，報表測試執行作業在完成前停止。
`void`	`testSkipped(TestDescription test, SkipReason reason)` Called when a test is skipped and did not execute for a reason that is not usually expected.
`void`	`testStarted(TestDescription test, long startTime)` `testStarted(com.android.tradefed.result.TestDescription)` 的替代方案，我們也會指定測試開始時間，並搭配 `ERROR(/#testEnded(com.android.tradefed.result.TestDescription,long,Map))` 進行準確的評估。
`void`	`testStarted(TestDescription test)` 回報個別測試案例的開始時間。

受保護的方法
`final void`	`clearModuleLogFiles()` 允許清除模組檔案，避免長時間攜帶。
`final void`	`clearResultsForName(String testRunName)` 可清除指定執行名稱的結果。
`final void`	`clearTestRunResults()` 可清除所有測試執行結果，避免保留過久。
`void`	`setIsAggregrateMetrics(boolean aggregate)` 切換「匯總指標」選項

公用建構函式

CollectingTestListener

public CollectingTestListener ()

公用方法

getBuildInfo

public IBuildInfo getBuildInfo ()

這個方法已淘汰。
依附於 getInvocationContext() 的 IBuildInfo。

傳回建構資訊。

傳回
`IBuildInfo`

getCurrentRunResults

public TestRunResult getCurrentRunResults ()

取得目前測試執行的結果。

請注意，結果可能不完整。建議您先測試 TestRunResult.isRunComplete() 和/或 (@link TestRunResult#isRunFailure()} 的值，再處理結果。

傳回
`TestRunResult`	`TestRunResult`，代表上次測試執行期間收集的資料

getExpectedTests

public int getExpectedTests ()

傳回預期測試次數。如果部分測試未執行，則可能與 getNumTotalTests() 不同。

傳回
`int`

getInvocationContext

public IInvocationContext getInvocationContext ()

傳回透過 invocationStarted(com.android.tradefed.invoker.IInvocationContext) 回報的叫用內容

傳回
`IInvocationContext`

getMergedTestRunResults

public  getMergedTestRunResults ()

傳回所有嘗試中所有執行的合併結果集合。

如果有多項結果，系統會合併每次的測試執行作業，並以最新的測試結果覆寫先前執行作業的測試結果。測試執行作業會依嘗試次數排序。

系統會根據 aggregate-metrics 設定的偏好設定，合併同一次嘗試的指標。最終指標會是最後一次嘗試的指標。

傳回

getModuleContextForRunResult

public IInvocationContext getModuleContextForRunResult (String testRunName)

傳回與結果相關聯的模組 IInvocationContext。

參數
`testRunName`	`String`：{`testRunStarted(String, int)` 提供的名稱。

傳回
`IInvocationContext`	如果該名稱沒有結果，則為指定測試執行名稱 `null` 的模組 `IInvocationContext`。

getModuleLogFiles

public MultiMap<String, LogFile> getModuleLogFiles ()

傳回地圖副本，內含與模組相關聯的所有記錄檔案

傳回
`MultiMap<String, LogFile>`

getNonAssociatedLogFiles

public MultiMap<String, LogFile> getNonAssociatedLogFiles ()

傳回地圖副本，其中包含所有未與測試執行或模組建立關聯的記錄檔案。

傳回
`MultiMap<String, LogFile>`

getNumAllFailedTestRuns

public int getNumAllFailedTestRuns ()

傳回處於失敗狀態的測試執行總數

傳回
`int`

getNumAllFailedTests

public int getNumAllFailedTests ()

傳回處於失敗狀態的測試總數 (僅限失敗，假設失敗不會計入)。

傳回
`int`

getNumTestsInState

public int getNumTestsInState (TestStatus status)

傳回這項執行作業中處於指定狀態的測試數量。

參數
`status`	`TestStatus`

傳回
`int`

getNumTestsInState

public int getNumTestsInState (TestResult.TestStatus ddmlibStatus)

與舊版狀態類型相容

參數
`ddmlibStatus`	`TestResult.TestStatus`

傳回
`int`

getNumTotalTests

public int getNumTotalTests ()

傳回所有執行作業的完整測試總數。

傳回
`int`

getPrimaryBuildInfo

public IBuildInfo getPrimaryBuildInfo ()

傳回透過 invocationStarted(com.android.tradefed.invoker.IInvocationContext) 回報的主要建構資訊。主要建構是執行中設定的第一個建構供應商傳回的建構。如果沒有內容 (沒有要測試案例的建構作業)，則傳回空值。

傳回
`IBuildInfo`

getRunResults

public  getRunResults ()

這個方法已淘汰。
使用 getMergedTestRunResults()

傳回所有測試執行的結果。

傳回

getTestRunAtAttempt

public TestRunResult getTestRunAtAttempt (String testRunName, 
                int attempt)

傳回 TestRunResult，進行單一嘗試。

參數
`testRunName`	`String`：{`testRunStarted(String, int)` 提供的名稱。
`attempt`	`int`：嘗試 ID。

傳回
`TestRunResult`	指定名稱和嘗試 ID 的 `TestRunResult`，或 `null` (如果不存在)。

getTestRunAttemptCount

public int getTestRunAttemptCount (String testRunName)

傳回指定測試執行名稱的嘗試次數。

參數
`testRunName`	`String`：{`testRunStarted(String, int)` 提供的名稱。

傳回
`int`

getTestRunAttempts

public  getTestRunAttempts (String testRunName)

取得指定測試執行的 TestRunResult 所有嘗試。

參數
`testRunName`	`String`：{`testRunStarted(String, int)` 提供的名稱。

傳回
	特定測試執行作業的所有 `TestRunResult`，依嘗試次數排序。

getTestRunForAttempts

public  getTestRunForAttempts (int attempt)

取得特定嘗試的所有結果。

參數
`attempt`	`int`：要取得結果的嘗試。

傳回
	特定嘗試的所有 `TestRunResult`。

getTestRunNames

public  getTestRunNames ()

傳回所有測試執行的所有名稱。

這些測試執行作業可能已多次執行，且每次嘗試都不同。

傳回

hasFailedTests

public boolean hasFailedTests ()

傳回叫用是否包含任何失敗或假設失敗的測試。

傳回
`boolean`

hasTestRunResultsForName

public boolean hasTestRunResultsForName (String testRunName)

傳回指定測試執行名稱是否有任何結果。

參數
`testRunName`	`String`：{`testRunStarted(String, int)` 提供的名稱。

傳回
`boolean`

invocationEnded

public void invocationEnded (long elapsedTime)

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

TradeFederation 架構會自動呼叫。

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

invocationFailed

public void invocationFailed (Throwable cause)

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

TradeFederation 架構會自動呼叫。

參數
`cause`	`Throwable`：`Throwable` 失敗的 `Throwable` 原因

invocationSkipped

public void invocationSkipped (SkipReason reason)

將叫用作業回報為已略過

參數
`reason`	`SkipReason`

invocationStarted

public void invocationStarted (IInvocationContext context)

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

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

參數
`context`	`IInvocationContext`：叫用相關資訊

isDisabled

public boolean isDisabled ()

如果整個物件都已停用 (略過設定和終止)，則傳回 True。否則傳回「false」。

傳回
`boolean`

logAssociation

public void logAssociation (String dataName, 
                LogFile logFile)

在某些情況下，記錄必須與測試案例緊密相關，但無法在直接 testLogSaved(String, com.android.tradefed.result.LogDataType, com.android.tradefed.result.InputStreamSource, com.android.tradefed.result.LogFile) 回呼中執行此操作。因此，這個回呼可明確提供強關聯。

參數
`dataName`	`String`：資料名稱
`logFile`	`LogFile`：先前記錄的 `LogFile`，應與測試案例建立關聯。

setBuildInfo

public void setBuildInfo (IBuildInfo buildInfo)

這個方法已淘汰。
現在不必再進行測試。

設定建構資訊。僅供測試。

參數
`buildInfo`	`IBuildInfo`

setDisable

public void setDisable (boolean isDisabled)

設定是否應停用物件。如果設為「Disabled」，表示應略過設定和拆除步驟。可用於在預設建構函式中，預設停用物件。

參數
`isDisabled`	`boolean`：物件應處於的狀態。

setMergeStrategy

public void setMergeStrategy (MergeStrategy strategy)

設定合併結果時要使用的 MergeStrategy。

參數
`strategy`	`MergeStrategy`

testAssumptionFailure

public void testAssumptionFailure (TestDescription test, 
                String trace)

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

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

testAssumptionFailure

public void testAssumptionFailure (TestDescription test, 
                FailureDescription failure)

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

參數
`test`	`TestDescription`：識別測試
`failure`	`FailureDescription`：`FailureDescription`，說明失敗情形和相關情境。

testEnded

public void testEnded (TestDescription test, 
                long endTime, 
                 testMetrics)

可直接指定結束時間的 ERROR(/#testEnded(com.android.tradefed.result.TestDescription,Map)) 替代方案。搭配 testStarted(com.android.tradefed.result.TestDescription, long) 使用，可準確測量。

參數
`test`	`TestDescription`：識別測試
`endTime`	`long`：測試結束時間，透過 `System.currentTimeMillis()` 測量
`testMetrics`	：發出的指標 `ERROR(/Map)`

testEnded

public void testEnded (TestDescription test, 
                 testMetrics)

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

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

參數
`test`	`TestDescription`：識別測試
`testMetrics`	：發出的指標 `ERROR(/Map)`

testFailed

public void testFailed (TestDescription test, 
                FailureDescription failure)

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

會在 testStarted 和 testEnded 之間呼叫。

參數
`test`	`TestDescription`：識別測試
`failure`	`FailureDescription`：`FailureDescription`，說明失敗情形和相關情境。

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`：識別測試

testModuleEnded

public void testModuleEnded ()

回報模組執行作業的結束時間。

testModuleStarted

public void testModuleStarted (IInvocationContext moduleContext)

回報模組的執行開始時間。這個回呼與 testModuleEnded() 相關聯，且在序列中為選用項目。只有在使用模組的執行期間，才會使用這個標記：以套件為基礎的執行器。

參數
`moduleContext`	`IInvocationContext`：模組的 `IInvocationContext`。

testRunEnded

public void testRunEnded (long elapsedTime, 
                 runMetrics)

報告測試執行結束時間。

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

testRunFailed

public void testRunFailed (FailureDescription failure)

由於 FailureDescription 所述的失敗情形，報表測試執行作業無法完成。

參數
`failure`	`FailureDescription`：`FailureDescription`，說明失敗情形和相關情境。

testRunFailed

public void testRunFailed (String errorMessage)

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

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

testRunStarted

public void testRunStarted (String name, 
                int numTests, 
                int attemptNumber)

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

參數
`name`	`String`：測試執行作業名稱
`numTests`	`int`：測試執行作業中的測試總數
`attemptNumber`	`int`：訂單號碼，用於識別相同 runName 的不同嘗試，該 runName 會多次執行。attemptNumber 是以 0 為索引，每次執行新作業時都應遞增。舉例來說，如果測試細部重試 3 次，則在相同 runName 下應有 4 次執行作業，且 attemptNumber 為 0 到 3。

testRunStarted

public void testRunStarted (String name, 
                int numTests)

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

參數
`name`	`String`：測試執行作業名稱
`numTests`	`int`：測試執行作業中的測試總數

testRunStarted

public void testRunStarted (String name, 
                int numTests, 
                int attemptNumber, 
                long startTime)

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

參數
`name`	`String`：測試執行作業名稱
`numTests`	`int`：測試執行作業中的測試總數
`attemptNumber`	`int`：訂單號碼，用於識別相同 runName 的不同嘗試，該 runName 會多次執行。attemptNumber 是以 0 為索引，每次執行新作業時都應遞增。舉例來說，如果測試細部重試 3 次，則在相同 runName 下應有 4 次執行作業，且 attemptNumber 為 0 到 3。
`startTime`	`long`：跑步開始時間，透過 `System.currentTimeMillis()` 測量

testRunStopped

public void testRunStopped (long elapsedTime)

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

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

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

testSkipped

public void testSkipped (TestDescription test, 
                SkipReason reason)

Called when a test is skipped and did not execute for a reason that is not usually expected. 系統會嘗試重試這些測試，以確保正常執行。

參數
`test`	`TestDescription`：識別測試
`reason`	`SkipReason`：`SkipReason`

testStarted

public void testStarted (TestDescription test, 
                long startTime)

testStarted(com.android.tradefed.result.TestDescription) 的替代方案，我們也會指定測試開始時間，並搭配 ERROR(/#testEnded(com.android.tradefed.result.TestDescription,long,Map)) 進行準確的評估。

參數
`test`	`TestDescription`：識別測試
`startTime`	`long`：測試開始時間，透過 `System.currentTimeMillis()` 測量

testStarted

public void testStarted (TestDescription test)

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

參數
`test`	`TestDescription`：識別測試

受保護的方法

clearModuleLogFiles

protected final void clearModuleLogFiles ()

允許清除模組檔案，避免長時間攜帶。

clearResultsForName

protected final void clearResultsForName (String testRunName)

可清除特定執行名稱的結果。建議僅在某些情況下使用，例如結果的匯總工具。

參數
`testRunName`	`String`

clearTestRunResults

protected final void clearTestRunResults ()

可清除所有測試執行結果，避免保留過久。

setIsAggregrateMetrics

protected void setIsAggregrateMetrics (boolean aggregate)

切換「匯總指標」選項

參數
`aggregate`	`boolean`