feat(core): make --reporters the canonical CLI flag (#1299)

Author: fi3ework

e2e/projects/index.test.ts

@@ -197,7 +197,7 @@ describe('test projects', () => {
           'run',
           '-c',
           'rstest.projectConfig.config.mts',
-          '--reporter',
+          '--reporters',
           'verbose',
         ],
         options: {
@@ -230,7 +230,7 @@ describe('test projects', () => {
           'run',
           '-c',
           'rstest.slowTest.config.mts',
-          '--reporter',
+          '--reporters',
           'verbose',
         ],
         options: {

e2e/reporter/githubActions.test.ts

@@ -15,7 +15,7 @@ it.skipIf(!process.env.CI)('github-actions', async () => {
 
   const { cli } = await runRstestCli({
     command: 'rstest',
-    args: ['run', 'githubActions', '--reporter', 'github-actions'],
+    args: ['run', 'githubActions', '--reporters', 'github-actions'],
     options: {
       nodeOptions: {
         cwd: __dirname,
@@ -93,7 +93,7 @@ it.skipIf(!process.env.CI)(
   async () => {
     const { cli } = await runRstestCli({
       command: 'rstest',
-      args: ['run', 'githubActions', '--reporter', 'github-actions'],
+      args: ['run', 'githubActions', '--reporters', 'github-actions'],
       options: {
         nodeOptions: {
           cwd: __dirname,
@@ -133,7 +133,7 @@ it.skipIf(!process.env.CI)('github-actions summary on pass', async () => {
       'run',
       '-c',
       './rstest.agentMd.pass.config.mts',
-      '--reporter',
+      '--reporters',
       'github-actions',
     ],
     options: {
@@ -198,7 +198,7 @@ it.skipIf(!process.env.CI)(
         'run',
         '-c',
         './rstest.githubActions.flaky.config.mts',
-        '--reporter',
+        '--reporters',
         'github-actions',
       ],
       options: {
@@ -255,7 +255,7 @@ it.skipIf(!process.env.CI)(
         'run',
         '-c',
         './rstest.githubActions.namedProject.config.mts',
-        '--reporter',
+        '--reporters',
         'github-actions',
       ],
       options: {
@@ -303,7 +303,7 @@ it.skipIf(!process.env.CI)(
     try {
       const { cli } = await runRstestCli({
         command: 'rstest',
-        args: ['run', 'githubActions', '--reporter', 'github-actions'],
+        args: ['run', 'githubActions', '--reporters', 'github-actions'],
         options: {
           nodeOptions: {
             cwd: __dirname,
@@ -348,7 +348,7 @@ it.skipIf(!process.env.CI)(
         'run',
         '-c',
         './rstest.agentMd.pass.config.mts',
-        '--reporter',
+        '--reporters',
         'github-actions',
       ],
       options: {
@@ -368,7 +368,7 @@ it.skipIf(!process.env.CI)(
 
     const failingRun = await runRstestCli({
       command: 'rstest',
-      args: ['run', 'githubActions', '--reporter', 'github-actions'],
+      args: ['run', 'githubActions', '--reporters', 'github-actions'],
       options: {
         nodeOptions: {
           cwd: __dirname,

e2e/reporter/index.test.ts

@@ -45,7 +45,7 @@ describe.concurrent('reporters', () => {
   it('verbose', async ({ onTestFinished }) => {
     const { cli } = await runRstestCli({
       command: 'rstest',
-      args: ['run', 'fixtures/index.test.ts', '--reporter=verbose'],
+      args: ['run', 'fixtures/index.test.ts', '--reporters=verbose'],
       onTestFinished,
       options: {
         nodeOptions: {
@@ -62,7 +62,7 @@ describe.concurrent('reporters', () => {
   it('dot', async ({ onTestFinished }) => {
     const { cli } = await runRstestCli({
       command: 'rstest',
-      args: ['run', 'fixtures/index.test.ts', '--reporter=dot'],
+      args: ['run', 'fixtures/index.test.ts', '--reporters=dot'],
       onTestFinished,
       options: {
         nodeOptions: {
@@ -110,7 +110,7 @@ describe.concurrent('reporters', () => {
       args: [
         'run',
         'fixtures/silent.test.ts',
-        '--reporter=dot',
+        '--reporters=dot',
         '--silent=passed-only',
       ],
       onTestFinished,
@@ -237,7 +237,7 @@ describe.concurrent('reporters', () => {
       args: [
         'run',
         'fixtures/index.test.ts',
-        '--reporter=verbose',
+        '--reporters=verbose',
         '--hideSkippedTests',
       ],
       onTestFinished,

e2e/reporter/json.test.ts

@@ -20,7 +20,7 @@ describe('json reporter', () => {
   it('should print structured JSON to stdout', async () => {
     const { cli } = await runRstestCli({
       command: 'rstest',
-      args: ['run', 'junit', '--reporter', 'json'],
+      args: ['run', 'junit', '--reporters', 'json'],
       options: {
         nodeOptions: {
           cwd: __dirname,

e2e/reporter/junit.test.ts

@@ -4,7 +4,7 @@ import { runRstestCli } from '../scripts';
 it('junit', async () => {
   const { cli, expectLog } = await runRstestCli({
     command: 'rstest',
-    args: ['run', 'junit', '--reporter', 'junit'],
+    args: ['run', 'junit', '--reporters', 'junit'],
     options: {
       nodeOptions: {
         cwd: __dirname,

e2e/reporter/mergeReports.test.ts

@@ -21,7 +21,7 @@ describe('merge-reports', () => {
     // Run shard 1/2 with blob reporter
     const { expectExecSuccess: shard1Success } = await runRstestCli({
       command: 'rstest',
-      args: ['run', '--shard', '1/2', '--reporter=blob'],
+      args: ['run', '--shard', '1/2', '--reporters=blob'],
       options: {
         nodeOptions: {
           cwd: fixturesDir,
@@ -38,7 +38,7 @@ describe('merge-reports', () => {
     // Run shard 2/2 with blob reporter
     const { expectExecSuccess: shard2Success } = await runRstestCli({
       command: 'rstest',
-      args: ['run', '--shard', '2/2', '--reporter=blob'],
+      args: ['run', '--shard', '2/2', '--reporters=blob'],
       options: {
         nodeOptions: {
           cwd: fixturesDir,
@@ -93,7 +93,7 @@ describe('merge-reports', () => {
         'run',
         '--shard',
         '1/2',
-        '--reporter=blob',
+        '--reporters=blob',
         '-c',
         'rstest.coverage.config.mts',
       ],
@@ -118,7 +118,7 @@ describe('merge-reports', () => {
         'run',
         '--shard',
         '2/2',
-        '--reporter=blob',
+        '--reporters=blob',
         '-c',
         'rstest.coverage.config.mts',
       ],

packages/core/src/cli/commands.ts

@@ -86,7 +86,7 @@ const runtimeOptionDefinitions: OptionDefinition[] = [
     '--slowTestThreshold <value>',
     'The number of milliseconds after which a test or suite is considered slow',
   ],
-  ['--reporter <reporter>', 'Specify the reporter to use'],
+  ['--reporters, --reporter <name>', 'Specify the reporter(s) to use'],
   [
     '-t, --testNamePattern <value>',
     'Run only tests with a name that matches the regex',
@@ -170,7 +170,7 @@ const mergeReportsOptionDefinitions: OptionDefinition[] = [
     'Specify the project root directory, can be an absolute path or a path relative to cwd',
   ],
   ['--coverage', 'Enable code coverage collection'],
-  ['--reporter <reporter>', 'Specify the reporter to use'],
+  ['--reporters, --reporter <name>', 'Specify the reporter(s) to use'],
   ['--cleanup', 'Remove blob reports directory after merging'],
 ];
 
@@ -226,6 +226,7 @@ const valueTakingOptions = new Set([
   '--pool.type',
   '--project',
   '--reporter',
+  '--reporters',
   '--retry',
   '--root',
   '--shard',

packages/core/src/cli/init.ts

@@ -51,7 +51,7 @@ export type CommonOptions = {
   isolate?: boolean;
   include?: string[];
   exclude?: string[];
-  reporter?: string[];
+  reporters?: string | string[];
   project?: string[];
   /**
    * Coverage options.
@@ -163,8 +163,8 @@ function mergeWithCLIOptions(
     config.passWithNoTests ??= true;
   }
 
-  if (options.reporter) {
-    config.reporters = castArray(options.reporter) as typeof config.reporters;
+  if (options.reporters) {
+    config.reporters = castArray(options.reporters) as typeof config.reporters;
   }
 
   if (options.shard) {
@@ -528,10 +528,10 @@ export async function initCli(options: CommonOptions): Promise<{
   });
 
   // In agent environments, default to markdown output when the user didn't
-  // explicitly set reporters (no `reporters` in config and no `--reporter`).
+  // explicitly set reporters (no `reporters` in config and no `--reporters`).
   if (
     determineAgent().isAgent &&
-    !options.reporter &&
+    !options.reporters &&
     config.reporters == null
   ) {
     config.reporters = ['md'];

packages/core/src/core/mergeReports.ts

@@ -22,7 +22,7 @@ function loadBlobFiles(blobDir: string): BlobData[] {
   if (!existsSync(blobDir)) {
     throw new Error(
       `Blob reports directory not found: ${color.cyan(blobDir)}\n` +
-        'Run tests with --reporter=blob first to generate shard reports.',
+        'Run tests with --reporters=blob first to generate shard reports.',
     );
   }
 
@@ -33,7 +33,7 @@ function loadBlobFiles(blobDir: string): BlobData[] {
   if (files.length === 0) {
     throw new Error(
       `No blob report files found in: ${color.cyan(blobDir)}\n` +
-        'Run tests with --reporter=blob first to generate shard reports.',
+        'Run tests with --reporters=blob first to generate shard reports.',
     );
   }
 

packages/core/tests/cli/commands.test.ts

@@ -214,6 +214,24 @@ describe('CLI help output', () => {
       name: 'chromium',
     });
   });
+
+  it('accepts --reporters and populates options.reporters', () => {
+    const parsed = createCli().parse(
+      ['node', 'rstest', 'run', '--reporters', 'verbose'],
+      { run: false },
+    );
+
+    expect(parsed.options.reporters).toBe('verbose');
+  });
+
+  it('accepts legacy --reporter as an alias for --reporters', () => {
+    const parsed = createCli().parse(
+      ['node', 'rstest', 'run', '--reporter', 'verbose', '--reporter=junit'],
+      { run: false },
+    );
+
+    expect(parsed.options.reporters).toEqual(['verbose', 'junit']);
+  });
 });
 
 describe('normalizeCliFilters', () => {