TS-38628 Tia Client doc cleanup

tia-client/src/main/kotlin/com/teamscale/tia/client/AgentHttpRequestFailedException.kt

@@ -6,7 +6,7 @@ package com.teamscale.tia.client
  * problems can be addressed.
  */
 class AgentHttpRequestFailedException : Exception {
-	constructor(message: String?) : super(message)
+	constructor(message: String) : super(message)
 
-	constructor(message: String?, cause: Throwable?) : super(message, cause)
+	constructor(message: String, cause: Throwable?) : super(message, cause)
 }

tia-client/src/main/kotlin/com/teamscale/tia/client/CommandLineInterface.kt

@@ -3,7 +3,6 @@ package com.teamscale.tia.client
 import com.teamscale.client.ClusteredTestDetails
 import com.teamscale.client.JsonUtils.deserializeList
 import com.teamscale.client.JsonUtils.serialize
-import com.teamscale.client.PrioritizableTestCluster
 import com.teamscale.client.StringUtils.isEmpty
 import com.teamscale.report.testwise.model.ETestExecutionResult
 import com.teamscale.report.testwise.model.TestExecution
@@ -15,7 +14,6 @@ import java.io.IOException
 import java.io.InputStreamReader
 import java.nio.charset.StandardCharsets
 import java.util.*
-import java.util.function.Supplier
 import java.util.stream.Collectors
 
 /**
@@ -24,8 +22,7 @@ import java.util.stream.Collectors
 class CommandLineInterface(arguments: Array<String>) {
 	private class InvalidCommandLineException(message: String?) : RuntimeException(message)
 
-	private val arguments: MutableList<String> =
-		ArrayList(listOf(*arguments))
+	private val arguments = listOf(*arguments).toMutableList()
 	private val command: String
 	private val api: ITestwiseCoverageAgentApi
 
@@ -50,8 +47,7 @@ class CommandLineInterface(arguments: Array<String>) {
 			"endTest" -> endTest()
 			"endTestRun" -> endTestRun()
 			else -> throw InvalidCommandLineException(
-				"Unknown command '" + command + "'. Should be one of startTestRun, startTest, endTest," +
-						" endTestRun"
+				"Unknown command '$command'. Should be one of startTestRun, startTest, endTest, endTestRun"
 			)
 		}
 	}
@@ -72,13 +68,11 @@ class CommandLineInterface(arguments: Array<String>) {
 	private fun endTest() {
 		if (arguments.size < 2) {
 			throw InvalidCommandLineException(
-				"You must provide the uniform path of the test that is about to be started" +
-						" as the first argument of the endTest command and the test result as the second."
+				"You must provide the uniform path of the test that is about to be started as the first argument of the endTest command and the test result as the second."
 			)
 		}
 		val uniformPath = arguments.removeAt(0)
 		val result = ETestExecutionResult.valueOf(arguments.removeAt(0).uppercase(Locale.getDefault()))
-
 		val message = readStdin()
 
 		// the agent already records test duration, so we can simply provide a dummy value here
@@ -109,10 +103,13 @@ class CommandLineInterface(arguments: Array<String>) {
 		val baselineRevision = parseAndRemoveStringParameter("baseline-revision")
 		val availableTests = parseAvailableTestsFromStdin()
 
-		val clusters = handleRequestError(
+		handleRequestError(
 			"Failed to start the test run"
-		) { api.testRunStarted(includeNonImpacted, baseline, baselineRevision, availableTests) }
-		println(serialize(clusters!!))
+		) {
+			api.testRunStarted(includeNonImpacted, baseline, baselineRevision, availableTests)
+		}?.let {
+			println(it.serialize())
+		}
 	}
 
 	@Throws(IOException::class)

tia-client/src/main/kotlin/com/teamscale/tia/client/ITestwiseCoverageAgentApi.kt

@@ -70,7 +70,7 @@ interface ITestwiseCoverageAgentApi {
 	): Call<List<PrioritizableTestCluster>>
 
 	/**
-	 * Test run finished. Generate test-wise coverage report and upload to Teamscale.
+	 * Test run finished. Generate a test-wise coverage report and upload to Teamscale.
 	 *
 	 * @param partial Whether the test recording only contains a subset of the available tests.
 	 */

tia-client/src/main/kotlin/com/teamscale/tia/client/TiaAgent.kt

@@ -56,8 +56,8 @@ class TiaAgent(private val includeNonImpactedTests: Boolean, url: HttpUrl) {
 
 	/**
 	 * Runs the TIA to determine which of the given available tests should be run and in which order. This method
-	 * considers all changes since the last time that test-wise coverage was uploaded. In most situations this is the
-	 * optimal behaviour.
+	 * has considered all changes since the last time that test-wise coverage was uploaded.
+	 * In most situations, this is the optimal behavior.
 	 *
 	 *
 	 * Using this method, Teamscale will perform the selection and prioritization based on the tests it currently knows
@@ -68,9 +68,9 @@ class TiaAgent(private val includeNonImpactedTests: Boolean, url: HttpUrl) {
 	 *
 	 * **Thus, we recommend that, if possible, you use [.startTestRun] instead.**
 	 *
-	 * @throws AgentHttpRequestFailedException e.g. if the agent or Teamscale is not reachable or an internal error
+	 * @throws AgentHttpRequestFailedException e.g., if the agent or Teamscale is not reachable or an internal error
 	 * occurs. This method already retries the request once, so this is likely a
-	 * terminal failure. You should simply fall back to running all tests in
+	 * terminal failure. You should fall back to running all tests in
 	 * this case and not communicate further with the agent. You should visibly
 	 * report this problem so it can be fixed.
 	 */
@@ -80,16 +80,17 @@ class TiaAgent(private val includeNonImpactedTests: Boolean, url: HttpUrl) {
 
 	/**
 	 * Runs the TIA to determine which of the given available tests should be run and in which order. This method
-	 * considers all changes since the given baseline timestamp.
+	 * has considered all changes since the given baseline timestamp.
 	 *
-	 * @param availableTests A list of all available tests. This is used to determine which tests need to be run, e.g.
+	 * @param availableTests A list of all available tests. This is used to determine which tests need to be run, e.g.,
 	 * because they are completely new or changed since the last run. If you provide an empty
-	 * list, no tests will be selected.The clustering information in this list is used to
+	 * list, no tests will be selected. The clustering information in this list is used to
 	 * construct the test clusters in the returned [TestRunWithClusteredSuggestions].
 	 * @param baseline       Consider all code changes since this date when calculating the impacted tests.
-	 * @param baselineRevision Same as baseline but accepts a revision (e.g. git SHA1) instead of a branch and timestamp
-	 * @throws AgentHttpRequestFailedException e.g. if the agent or Teamscale is not reachable or an internal error
-	 * occurs. You should simply fall back to running all tests in this case.
+	 * @param baselineRevision Same as baseline but accepts a revision (e.g., git SHA1) instead of a branch and timestamp
+	 * @throws AgentHttpRequestFailedException e.g., if the agent or Teamscale is not reachable or an internal error
+	 * occurs.
+	 * You should fall back to running all tests in this case.
 	 */
 	@Throws(AgentHttpRequestFailedException::class)
 	fun startTestRun(
@@ -133,9 +134,8 @@ class TiaAgent(private val includeNonImpactedTests: Boolean, url: HttpUrl) {
 	fun startTestRunAssumingUnchangedTests(
 		baseline: Instant?, baselineRevision: String?
 	): TestRunWithFlatSuggestions {
-		val baselineTimestamp = baseline?.toEpochMilli()
 		val clusters = handleRequestError("Failed to start the test run") {
-			api.testRunStarted(includeNonImpactedTests, baselineTimestamp, baselineRevision)
+			api.testRunStarted(includeNonImpactedTests, baseline?.toEpochMilli(), baselineRevision)
 		}
 		return TestRunWithFlatSuggestions(api, clusters?.firstOrNull()?.tests ?: emptyList())
 	}