Add --debug option for integration tests

Author: wleczny

README.md

@@ -45,6 +45,16 @@ Filter test suites with
 ./mill integration.test.jvm 'scala.cli.integration.RunTestsDefault.Multiple scripts'
 ```
 
+Pass the `--debug` option to debug integration tests:
+```bash
+./mill integration.test.jvm 'scala.cli.integration.RunTestsDefault.*' --debug
+```
+
+The debug option uses 5005 port by default. It is possible to change it as follows:
+```bash
+./mill integration.test.jvm 'scala.cli.integration.RunTestsDefault.*' --debug:5006
+```
+
 #### Run integration tests with the native launcher
 
 (generating the launcher can take several minutes)

build.sc

@@ -855,11 +855,24 @@ trait CliIntegration extends SbtModule with ScalaCliPublishModule with HasTests
       def test(args: String*) = {
         val argsTask = T.task {
           val launcher = launcherTask().path
+          val debugReg = "^--debug$|^--debug:([0-9]+)$".r
+          val debugPortOpt = args.find(debugReg.matches).flatMap {
+            case debugReg(port) => Option(port).orElse(Some("5005"))
+            case _              => None
+          }
+          val debugArgs = debugPortOpt match {
+            case Some(port) =>
+              System.err.println(
+                s"--debug option has been passed. Listening for transport dt_socket at address: $port"
+              )
+              Seq(s"-Dtest.scala-cli.debug.port=$port")
+            case _ => Seq.empty
+          }
           val extraArgs = Seq(
             s"-Dtest.scala-cli.path=$launcher",
             s"-Dtest.scala-cli.kind=$cliKind"
           )
-          args ++ extraArgs
+          args ++ extraArgs ++ debugArgs
         }
         T.command {
           val res            = testTask(argsTask, T.task(Seq.empty[String]))()

modules/integration/src/test/scala/scala/cli/integration/TestUtil.scala

@@ -12,18 +12,29 @@ import scala.util.Properties
 
 object TestUtil {
 
-  val cliKind: String      = sys.props("test.scala-cli.kind")
-  val isNativeCli: Boolean = cliKind.startsWith("native")
-  val isCI: Boolean        = System.getenv("CI") != null
-  val cliPath: String      = sys.props("test.scala-cli.path")
-  val detectCliPath        = if (TestUtil.isNativeCli) TestUtil.cliPath else "scala-cli"
-  val cli: Seq[String]     = cliCommand(cliPath)
+  val cliKind: String              = sys.props("test.scala-cli.kind")
+  val isNativeCli: Boolean         = cliKind.startsWith("native")
+  val isCI: Boolean                = System.getenv("CI") != null
+  val cliPath: String              = sys.props("test.scala-cli.path")
+  val debugPortOpt: Option[String] = sys.props.get("test.scala-cli.debug.port")
+  val detectCliPath                = if (TestUtil.isNativeCli) TestUtil.cliPath else "scala-cli"
+  val cli: Seq[String]             = cliCommand(cliPath)
 
   def cliCommand(cliPath: String): Seq[String] =
     if (isNativeCli)
       Seq(cliPath)
     else
-      Seq("java", "-Xmx512m", "-Xms128m", "-jar", cliPath)
+      debugPortOpt match {
+        case Some(port) => Seq(
+            "java",
+            "-Xmx512m",
+            "-Xms128m",
+            s"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=$port,quiet=y",
+            "-jar",
+            cliPath
+          )
+        case _ => Seq("java", "-Xmx512m", "-Xms128m", "-jar", cliPath)
+      }
 
   // format: off
   val extraOptions: List[String] = List(