feat(test): add --parallel flag, soft deprecate --jobs (#15259)

Co-authored-by: mrkldshv <markladyshev@gmail.com>

cli/args/flags.rs

@@ -480,10 +480,9 @@ static ENV_VARIABLES_HELP: &str = r#"ENVIRONMENT VARIABLES:
     DENO_NO_PROMPT       Set to disable permission prompts on access
                          (alternative to passing --no-prompt on invocation)
     DENO_WEBGPU_TRACE    Directory to use for wgpu traces
-    DENO_JOBS            Number of parallel workers used for test subcommand.
-                         Defaults to number of available CPUs when used with
-                         --jobs flag and no value is provided.
-                         Defaults to 1 when --jobs flag is not used.
+    DENO_JOBS            Number of parallel workers used for the --parallel
+                         flag with the test subcommand. Defaults to number
+                         of available CPUs.
     HTTP_PROXY           Proxy address for HTTP requests
                          (module downloads, fetch)
     HTTPS_PROXY          Proxy address for HTTPS requests
@@ -1548,11 +1547,19 @@ fn test_subcommand<'a>() -> Command<'a> {
         .conflicts_with("inspect-brk")
         .help("UNSTABLE: Collect coverage profile data into DIR"),
     )
+    .arg(
+      Arg::new("parallel")
+        .long("parallel")
+        .help("Run test modules in parallel. Parallelism defaults to the number of available CPUs or the value in the DENO_JOBS environment variable.")
+        .conflicts_with("jobs")
+        .takes_value(false)
+    )
     .arg(
       Arg::new("jobs")
         .short('j')
         .long("jobs")
-        .help("Number of parallel workers, defaults to number of available CPUs when no value is provided. Defaults to 1 when the option is not present.")
+        .help("deprecated: Number of parallel workers, defaults to number of available CPUs when no value is provided. Defaults to 1 when the option is not present.")
+        .hide(true)
         .min_values(0)
         .max_values(1)
         .takes_value(true)
@@ -2667,10 +2674,8 @@ fn test_parse(flags: &mut Flags, matches: &clap::ArgMatches) {
     }
   }
 
-  let concurrent_jobs = if matches.is_present("jobs") {
-    if let Some(value) = matches.value_of("jobs") {
-      value.parse().unwrap()
-    } else if let Ok(value) = env::var("DENO_JOBS") {
+  let concurrent_jobs = if matches.is_present("parallel") {
+    if let Ok(value) = env::var("DENO_JOBS") {
       value
         .parse::<NonZeroUsize>()
         .unwrap_or(NonZeroUsize::new(1).unwrap())
@@ -2678,6 +2683,17 @@ fn test_parse(flags: &mut Flags, matches: &clap::ArgMatches) {
       std::thread::available_parallelism()
         .unwrap_or(NonZeroUsize::new(1).unwrap())
     }
+  } else if matches.is_present("jobs") {
+    println!(
+      "{}",
+      crate::colors::yellow("Warning: --jobs flag is deprecated. Use the --parallel flag with possibly the 'DENO_JOBS' environment variable."),
+    );
+    if let Some(value) = matches.value_of("jobs") {
+      value.parse().unwrap()
+    } else {
+      std::thread::available_parallelism()
+        .unwrap_or(NonZeroUsize::new(1).unwrap())
+    }
   } else {
     NonZeroUsize::new(1).unwrap()
   };

cli/tests/integration/test_tests.rs

@@ -80,30 +80,29 @@ itest!(test_with_malformed_config {
   output: "test/collect_with_malformed_config.out",
 });
 
-itest!(jobs_flag {
-  args: "test test/short-pass.ts --jobs",
+itest!(parallel_flag {
+  args: "test test/short-pass.ts --parallel",
   exit_code: 0,
   output: "test/short-pass.out",
 });
 
-itest!(jobs_flag_with_numeric_value {
-  args: "test test/short-pass.ts --jobs=2",
-  exit_code: 0,
-  output: "test/short-pass-jobs-flag-with-numeric-value.out",
-});
-
-itest!(jobs_flag_with_env_variable {
-  args: "test test/short-pass.ts --jobs",
+itest!(parallel_flag_with_env_variable {
+  args: "test test/short-pass.ts --parallel",
   envs: vec![("DENO_JOBS".to_owned(), "2".to_owned())],
   exit_code: 0,
   output: "test/short-pass.out",
 });
 
-itest!(jobs_flag_with_numeric_value_and_env_var {
-  args: "test test/short-pass.ts --jobs=2",
-  envs: vec![("DENO_JOBS".to_owned(), "3".to_owned())],
+itest!(jobs_flag {
+  args: "test test/short-pass.ts --jobs",
   exit_code: 0,
-  output: "test/short-pass-jobs-flag-with-numeric-value.out",
+  output: "test/short-pass-jobs-flag-warning.out",
+});
+
+itest!(jobs_flag_with_numeric_value {
+  args: "test test/short-pass.ts --jobs=2",
+  exit_code: 0,
+  output: "test/short-pass-jobs-flag-warning.out",
 });
 
 itest!(load_unload {

cli/tests/testdata/test/short-pass-jobs-flag-warning.out

@@ -1,3 +1,4 @@
+Warning: --jobs flag is deprecated. Use the --parallel flag with possibly the 'DENO_JOBS' environment variable.
 Check [WILDCARD]/test/short-pass.ts
 running 1 test from ./test/short-pass.ts
 test ... ok ([WILDCARD])