feat(cli): allow percentage-based concurrency configuration (e.g., "50%") (#5818)

- Allow concurrency option to accept percentage strings (e.g., "50%") in addition to absolute numbers
- Switch from os.cpus() to os.availableParallelism() for more
  accurate CPU count detection

Author: jaspervdveen

docs/configuration.md

@@ -126,14 +126,16 @@ Settings for the `clear-text` reporter.
 - `reportScoreTable`: Indicates whether or not to log score table.
 - `skipFull`: Indicates whether rows with 100% mutation score are hidden in the score table.
 
-### `concurrency` [`number`]
+### `concurrency` [`number` \| `string`]
 
 Default: `cpuCoreCount <= 4? cpuCoreCount : cpuCoreCount - 1`<br />
-Command line: `--concurrency 4`<br />
-Config file: `"concurrency": 4`
+Command line: `--concurrency 4` or `--concurrency 50%`<br />
+Config file: `"concurrency": 4` or `"concurrency": "50%"`
 
 Set the concurrency of workers. This defaults to `n-1` where `n` is the number of logical CPU cores available on your machine, unless `n <= 4`, in that case it uses `n`. This is a sane default for most use cases.
 
+You can also specify a percentage string (e.g., `"50%"`) to compute the worker count as a percentage of the available CPU cores. For example, on an 8-core machine, `"50%"` results in 4 workers. The minimum is always 1 worker.
+
 ### `commandRunner` [`object`]
 
 Default: `{ command: 'npm test' }`<br />

docs/parallel-workers.md

@@ -3,7 +3,7 @@ title: Parallel Workers
 custom_edit_url: https://github.com/stryker-mutator/stryker-js/edit/master/docs/parallel-workers.md
 ---
 
-Stryker will always run checkers and test runners in parallel by creating worker processes (note, not `worker_threads`). The number of such processes forked is determined by the configuration option [`--concurrency`](./configuration.md#concurrency-number). 
+Stryker will always run checkers and test runners in parallel by creating worker processes (note, not `worker_threads`). The number of such processes forked is determined by the configuration option [`--concurrency`](./configuration.md#concurrency-number--string). You can specify a number (e.g., `4`) or a percentage of CPU cores (e.g., `"50%"`). 
 
 However, imagine running these parallel processes on a test suite which uses resources like a database connection, web server or file system. This means these processes can conflict if they write to the same database, file or utilize the same port.
 

packages/api/schema/stryker-core.json

@@ -292,8 +292,18 @@
       }
     },
     "concurrency": {
-      "description": "Set the concurrency of workers. Stryker will always run checkers and test runners in parallel by creating worker processes (note, not `worker_threads`). This defaults to `n-1` where `n` is the number of logical CPU cores available on your machine, unless `n <= 4`, in that case it uses `n`. This is a sane default for most use cases.",
-      "type": "number"
+      "description": "Set the concurrency of workers. Stryker will always run checkers and test runners in parallel by creating worker processes (note, not `worker_threads`). This defaults to `n-1` where `n` is the number of logical CPU cores available on your machine, unless `n <= 4`, in that case it uses `n`. This is a sane default for most use cases. You can also specify a percentage string (e.g., \"50%\") to compute the worker count as a percentage of the logical CPU cores available (0%-100%).",
+      "oneOf": [
+        {
+          "type": "number",
+          "minimum": 1
+        },
+        {
+          "type": "string",
+          "pattern": "^(100|[1-9]?[0-9])%$"
+        }
+      ],
+      "examples": [4, "50%", "100%"]
     },
     "commandRunner": {
       "description": "Options used by the command test runner. Note: these options will only be used when the command test runner is activated (this is the default)",

packages/core/src/concurrent/concurrency-token-provider.ts

@@ -24,9 +24,11 @@ export class ConcurrencyTokenProvider implements Disposable {
     options: Pick<StrykerOptions, 'checkers' | 'concurrency'>,
     private readonly log: Logger,
   ) {
-    const cpuCount = os.cpus().length;
-    const concurrency =
-      options.concurrency ?? (cpuCount > 4 ? cpuCount - 1 : cpuCount);
+    const availableParallelism = os.availableParallelism();
+    const concurrency = this.computeConcurrency(
+      options.concurrency,
+      availableParallelism,
+    );
     if (options.checkers.length > 0) {
       this.concurrencyCheckers = Math.max(Math.ceil(concurrency / 2), 1);
       this.checkerToken$ = range(this.concurrencyCheckers);
@@ -50,6 +52,36 @@ export class ConcurrencyTokenProvider implements Disposable {
     );
   }
 
+  private computeConcurrency(
+    concurrencyOption: number | string | undefined,
+    availableParallelism: number,
+  ): number {
+    if (typeof concurrencyOption === 'string') {
+      const percentageMatch = concurrencyOption.match(/^(100|[1-9]?[0-9])%$/);
+      if (percentageMatch) {
+        const percentage = parseInt(percentageMatch[1], 10);
+        const computed = Math.max(
+          1,
+          Math.round((availableParallelism * percentage) / 100),
+        );
+        this.log.debug(
+          'Computed concurrency %s from "%s" based on %s available parallelism.',
+          computed,
+          concurrencyOption,
+          availableParallelism,
+        );
+        return computed;
+      }
+    }
+    if (typeof concurrencyOption === 'number') {
+      return concurrencyOption;
+    }
+    // Default: n-1 for n > 4, else n
+    return availableParallelism > 4
+      ? availableParallelism - 1
+      : availableParallelism;
+  }
+
   public freeCheckers(): void {
     if (this.concurrencyCheckers > 0) {
       this.log.debug(

packages/core/src/config/options-validator.ts

@@ -175,7 +175,7 @@ export class OptionsValidator {
       );
       if (
         !options.concurrency &&
-        options.maxConcurrentTestRunners < os.cpus().length - 1
+        options.maxConcurrentTestRunners < os.availableParallelism() - 1
       ) {
         options.concurrency = options.maxConcurrentTestRunners;
       }

packages/core/src/stryker-cli.ts

@@ -31,6 +31,15 @@ function parseCleanDirOption(val: string) {
   return v === 'always' ? v : v !== 'false' && v !== '0';
 }
 
+function parseConcurrency(val: string): number | string {
+  // If it's a pure number, parse as integer
+  if (/^\d+$/.test(val)) {
+    return parseInt(val, 10);
+  }
+  // Otherwise keep as string (for percentage values like "50%")
+  return val;
+}
+
 const configFileArgument = new Argument(
   '[configFile]',
   'Path to the config file',
@@ -262,7 +271,7 @@ export class StrykerCli {
       .option(
         '-c, --concurrency <n>',
         'Set the concurrency of workers. Stryker will always run checkers and test runners in parallel by creating worker processes (default: cpuCount - 1)',
-        parseInt,
+        parseConcurrency,
       )
       .option(
         '--disableBail',

packages/core/test/unit/concurrent/concurrency-token-provider.spec.ts

@@ -6,7 +6,6 @@ import { lastValueFrom, toArray } from 'rxjs';
 import { testInjector } from '@stryker-mutator/test-helpers';
 
 import { ConcurrencyTokenProvider } from '../../../src/concurrent/index.js';
-import { createCpuInfo } from '../../helpers/producers.js';
 
 describe(ConcurrencyTokenProvider.name, () => {
   function createSut() {
@@ -36,30 +35,15 @@ describe(ConcurrencyTokenProvider.name, () => {
   });
 
   describe('testRunnerToken$', () => {
-    it('should use cpuCount if concurrency is not set and CPU count <= 4', async () => {
-      sinon
-        .stub(os, 'cpus')
-        .returns([
-          createCpuInfo(),
-          createCpuInfo(),
-          createCpuInfo(),
-          createCpuInfo(),
-        ]);
+    it('should use availableParallelism if concurrency is not set and availableParallelism <= 4', async () => {
+      sinon.stub(os, 'availableParallelism').returns(4);
       const sut = createSut();
       const actualTokens = await actAllTestRunnerTokens(sut);
       expect(actualTokens).deep.eq([0, 1, 2, 3]);
     });
 
-    it('should use cpuCount - 1 if concurrency is not set and CPU count > 4', async () => {
-      sinon
-        .stub(os, 'cpus')
-        .returns([
-          createCpuInfo(),
-          createCpuInfo(),
-          createCpuInfo(),
-          createCpuInfo(),
-          createCpuInfo(),
-        ]);
+    it('should use availableParallelism - 1 if concurrency is not set and availableParallelism > 4', async () => {
+      sinon.stub(os, 'availableParallelism').returns(5);
       const sut = createSut();
       const actualTokens = await actAllTestRunnerTokens(sut);
       expect(actualTokens).deep.eq([0, 1, 2, 3]);
@@ -130,6 +114,98 @@ describe(ConcurrencyTokenProvider.name, () => {
     });
   });
 
+  describe('concurrency percentage', () => {
+    it('should convert "50%" to half of available parallelism', () => {
+      sinon.stub(os, 'availableParallelism').returns(8);
+      testInjector.options.concurrency = '50%';
+      const sut = createSut();
+      expect(testInjector.logger.debug).calledWith(
+        'Computed concurrency %s from "%s" based on %s available parallelism.',
+        4,
+        '50%',
+        8,
+      );
+      sut.dispose();
+    });
+
+    it('should convert "100%" to full available parallelism', () => {
+      sinon.stub(os, 'availableParallelism').returns(4);
+      testInjector.options.concurrency = '100%';
+      const sut = createSut();
+      expect(testInjector.logger.debug).calledWith(
+        'Computed concurrency %s from "%s" based on %s available parallelism.',
+        4,
+        '100%',
+        4,
+      );
+      sut.dispose();
+    });
+
+    it('should round to nearest integer', () => {
+      sinon.stub(os, 'availableParallelism').returns(3);
+      testInjector.options.concurrency = '50%';
+      const sut = createSut();
+      // 3 * 0.5 = 1.5, rounded to 2
+      expect(testInjector.logger.debug).calledWith(
+        'Computed concurrency %s from "%s" based on %s available parallelism.',
+        2,
+        '50%',
+        3,
+      );
+      sut.dispose();
+    });
+
+    it('should enforce minimum of 1 for "0%"', () => {
+      sinon.stub(os, 'availableParallelism').returns(2);
+      testInjector.options.concurrency = '0%';
+      const sut = createSut();
+      expect(testInjector.logger.debug).calledWith(
+        'Computed concurrency %s from "%s" based on %s available parallelism.',
+        1,
+        '0%',
+        2,
+      );
+      sut.dispose();
+    });
+
+    it('should not convert invalid percentage format like "abc50%" as percentage', () => {
+      sinon.stub(os, 'availableParallelism').returns(8);
+      testInjector.options.concurrency = 'abc50%';
+      const sut = createSut();
+      // Should use default logic (availableParallelism - 1 since 8 > 4)
+      expect(testInjector.logger.info).calledWith(
+        'Creating %s test runner process(es).',
+        7,
+      );
+      sut.dispose();
+    });
+
+    it('should not convert percentages over 100% because they fail schema validation', () => {
+      sinon.stub(os, 'availableParallelism').returns(8);
+      // This scenario should be prevented by schema validation, but test defensive code
+      testInjector.options.concurrency = '150%';
+      const sut = createSut();
+      // Should use default logic (availableParallelism - 1 since 8 > 4)
+      expect(testInjector.logger.info).calledWith(
+        'Creating %s test runner process(es).',
+        7,
+      );
+      sut.dispose();
+    });
+
+    it('should not convert invalid percentage format like "50%abc" as percentage', () => {
+      sinon.stub(os, 'availableParallelism').returns(8);
+      testInjector.options.concurrency = '50%abc' as any;
+      const sut = createSut();
+      // Should use default logic (availableParallelism - 1 since 8 > 4)
+      expect(testInjector.logger.info).calledWith(
+        'Creating %s test runner process(es).',
+        7,
+      );
+      sut.dispose();
+    });
+  });
+
   describe('dispose', () => {
     it('should complete the subject(s)', () => {
       // Arrange

packages/core/test/unit/config/options-validator.spec.ts

@@ -13,7 +13,6 @@ import { expect } from 'chai';
 
 import { OptionsValidator } from '../../../src/config/options-validator.js';
 import { coreTokens } from '../../../src/di/index.js';
-import { createCpuInfo } from '../../helpers/producers.js';
 import { optionsPath } from '../../../src/utils/index.js';
 
 describe(OptionsValidator.name, () => {
@@ -410,25 +409,67 @@ describe(OptionsValidator.name, () => {
       );
     });
 
-    it('should not configure "concurrency" if "maxConcurrentTestRunners" is >= cpus-1', () => {
+    it('should not configure "concurrency" if "maxConcurrentTestRunners" is >= availableParallelism-1', () => {
       testInjector.options.maxConcurrentTestRunners = 2;
-      sinon
-        .stub(os, 'cpus')
-        .returns([createCpuInfo(), createCpuInfo(), createCpuInfo()]);
+      sinon.stub(os, 'availableParallelism').returns(3);
       sut.validate(testInjector.options);
       expect(testInjector.options.concurrency).undefined;
     });
 
     it('should configure "concurrency" if "maxConcurrentTestRunners" is set with a lower value', () => {
       testInjector.options.maxConcurrentTestRunners = 1;
-      sinon
-        .stub(os, 'cpus')
-        .returns([createCpuInfo(), createCpuInfo(), createCpuInfo()]);
+      sinon.stub(os, 'availableParallelism').returns(3);
       sut.validate(testInjector.options);
       expect(testInjector.options.concurrency).eq(1);
     });
   });
 
+  describe('concurrency percentage', () => {
+    it('should accept "50%" as a valid percentage', () => {
+      testInjector.options.concurrency = '50%';
+      sut.validate(testInjector.options);
+      expect(testInjector.options.concurrency).eq('50%');
+    });
+
+    it('should accept "100%" as a valid percentage', () => {
+      testInjector.options.concurrency = '100%';
+      sut.validate(testInjector.options);
+      expect(testInjector.options.concurrency).eq('100%');
+    });
+
+    it('should accept "0%" as a valid percentage', () => {
+      testInjector.options.concurrency = '0%';
+      sut.validate(testInjector.options);
+      expect(testInjector.options.concurrency).eq('0%');
+    });
+
+    it('should reject percentages over 100%', () => {
+      testInjector.options.concurrency = '101%';
+      expect(() => sut.validate(testInjector.options)).throws();
+    });
+
+    it('should reject invalid percentage format', () => {
+      testInjector.options.concurrency = '50';
+      expect(() => sut.validate(testInjector.options)).throws();
+    });
+
+    it('should reject percentages with prefix like "abc50%"', () => {
+      testInjector.options.concurrency = 'abc50%';
+      expect(() => sut.validate(testInjector.options)).throws();
+    });
+
+    it('should reject percentages with suffix like "50%abc"', () => {
+      testInjector.options.concurrency = '50%abc';
+      expect(() => sut.validate(testInjector.options)).throws();
+    });
+
+    it('should not modify numeric concurrency values', () => {
+      testInjector.options.concurrency = 4;
+      sut.validate(testInjector.options);
+      expect(testInjector.options.concurrency).eq(4);
+    });
+  });
+
   it('should be invalid with non-numeric maxTestRunnerReuse', () => {
     breakConfig('maxTestRunnerReuse', 'break');
     actValidationErrors(

packages/core/test/unit/stryker-cli.spec.ts

@@ -81,9 +81,12 @@ describe(StrykerCli.name, () => {
         [['--force'], { force: true }],
         [['--ignoreStatic'], { ignoreStatic: true }],
         [['--concurrency', '5'], { concurrency: 5 }],
+        [['--concurrency', '50%'], { concurrency: '50%' }],
         [['--cleanTempDir', 'false'], { cleanTempDir: false }],
         [['--cleanTempDir', 'always'], { cleanTempDir: 'always' }],
         [['-c', '6'], { concurrency: 6 }],
+        [['-c', '12'], { concurrency: 12 }],
+        [['-c', '100%'], { concurrency: '100%' }],
         [['--maxTestRunnerReuse', '3'], { maxTestRunnerReuse: 3 }],
       ];
       testCases.forEach(([args, expected]) => {