feat: support filter projects via --project option (#520)

Author: 9aoy

e2e/projects/filter.test.ts

@@ -25,4 +25,23 @@ describe('test projects filter', () => {
     expect(logs.find((log) => log.includes('node/test/index'))).toBeFalsy();
     expect(logs.find((log) => log.includes('client/test/index'))).toBeTruthy();
   });
+
+  it('should run test success with project filter', async () => {
+    const { cli, expectExecSuccess } = await runRstestCli({
+      command: 'rstest',
+      args: ['run', '--project', 'node', '--globals'],
+      options: {
+        nodeOptions: {
+          cwd: join(__dirname, 'fixtures'),
+        },
+      },
+    });
+
+    await expectExecSuccess();
+    const logs = cli.stdout.split('\n').filter(Boolean);
+
+    // test log print
+    expect(logs.find((log) => log.includes('node/test/index'))).toBeTruthy();
+    expect(logs.find((log) => log.includes('client/test/index'))).toBeFalsy();
+  });
 });

packages/core/src/cli/commands.ts

@@ -34,6 +34,10 @@ const applyCommonOptions = (cli: CAC) => {
     .option('--include <include>', 'Match test files')
     .option('--exclude <exclude>', 'Exclude files from test')
     .option('-u, --update', 'Update snapshot files')
+    .option(
+      '--project <name>',
+      'Run only projects that match the name, can be a full name or wildcards pattern',
+    )
     .option(
       '--passWithNoTests',
       'Allows the test suite to pass when no files are found',

packages/core/src/cli/init.ts

@@ -4,7 +4,13 @@ import { basename, dirname, resolve } from 'pathe';
 import { type GlobOptions, glob, isDynamicPattern } from 'tinyglobby';
 import { loadConfig } from '../config';
 import type { Project, RstestConfig } from '../types';
-import { castArray, getAbsolutePath, logger } from '../utils';
+import {
+  castArray,
+  color,
+  filterProjects,
+  getAbsolutePath,
+  logger,
+} from '../utils';
 
 export type CommonOptions = {
   root?: string;
@@ -15,6 +21,7 @@ export type CommonOptions = {
   include?: string[];
   exclude?: string[];
   reporter?: string[];
+  project?: string[];
   passWithNoTests?: boolean;
   printConsoleTrace?: boolean;
   disableConsoleIntercept?: boolean;
@@ -99,7 +106,7 @@ export async function resolveProjects({
   root: string;
   options: CommonOptions;
 }): Promise<Project[]> {
-  if (!config.projects || !config.projects.length) {
+  if (!config.projects) {
     return [];
   }
 
@@ -174,7 +181,18 @@ export async function resolveProjects({
         configFilePath,
       };
     }),
-  );
+  ).then((projects) => filterProjects(projects, options));
+
+  if (!projects.length) {
+    let errorMsg = `No projects found, please make sure you have at least one valid project.
+${color.gray('projects:')} ${JSON.stringify(config.projects, null, 2)}`;
+
+    if (options.project) {
+      errorMsg += `\n${color.gray('projectName filter:')} ${JSON.stringify(options.project, null, 2)}`;
+    }
+
+    throw errorMsg;
+  }
 
   const names = new Set<string>();
 

packages/core/src/utils/testFiles.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import pathe from 'pathe';
 import { glob } from 'tinyglobby';
+import type { Project } from '../types';
 import { castArray, color, getAbsolutePath, parsePosix } from './helper';
 
 export const filterFiles = (
@@ -38,6 +39,32 @@ export const filterFiles = (
   });
 };
 
+export const filterProjects = (
+  projects: Project[],
+  options: {
+    project?: string[];
+  },
+): Project[] => {
+  if (options.project) {
+    const regexes = castArray(options.project).map((pattern) => {
+      // cast wildcard to RegExp, eg. @rstest/*, !@rstest/core
+      const isNeg = pattern.startsWith('!');
+
+      const escaped = (isNeg ? pattern.slice(1) : pattern)
+        .split('*')
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*');
+      return new RegExp(isNeg ? `^(?!${escaped})` : `^${escaped}$`);
+    });
+
+    return projects.filter((proj) =>
+      regexes.some((re) => re.test(proj.config.name!)),
+    );
+  }
+
+  return projects;
+};
+
 const hasInSourceTestCode = (code: string): boolean =>
   code.includes('import.meta.rstest');
 

packages/core/tests/utils/testFiles.test.ts

@@ -1,5 +1,9 @@
 import path from 'node:path';
-import { filterFiles, formatTestEntryName } from '../../src/utils/testFiles';
+import {
+  filterFiles,
+  filterProjects,
+  formatTestEntryName,
+} from '../../src/utils/testFiles';
 
 describe('test filterFiles', () => {
   it('should filter files correctly', () => {
@@ -29,3 +33,59 @@ test('formatTestEntryName', () => {
   expect(formatTestEntryName('some.setup.ts')).toBe('some~setup~ts');
   expect(formatTestEntryName('some/setup.ts')).toBe('some_setup~ts');
 });
+
+test('filterProjects', () => {
+  const projects = [
+    {
+      config: { name: '@rstest/core' },
+      relativeRoot: 'packages/core',
+    },
+    {
+      config: { name: '@rstest/coverage' },
+      relativeRoot: 'packages/coverage',
+    },
+    {
+      config: { name: 'react' },
+      relativeRoot: 'example/react',
+    },
+  ];
+
+  expect(filterProjects(projects, {})).toEqual(projects);
+
+  expect(
+    filterProjects(projects, {
+      project: ['@rstest/core'],
+    }),
+  ).toEqual([
+    {
+      config: { name: '@rstest/core' },
+      relativeRoot: 'packages/core',
+    },
+  ]);
+
+  expect(
+    filterProjects(projects, {
+      project: ['@rstest/*'],
+    }),
+  ).toEqual([
+    {
+      config: { name: '@rstest/core' },
+      relativeRoot: 'packages/core',
+    },
+    {
+      config: { name: '@rstest/coverage' },
+      relativeRoot: 'packages/coverage',
+    },
+  ]);
+
+  expect(
+    filterProjects(projects, {
+      project: ['!@rstest/*'],
+    }),
+  ).toEqual([
+    {
+      config: { name: 'react' },
+      relativeRoot: 'example/react',
+    },
+  ]);
+});

website/docs/en/config/test/name.mdx

@@ -4,3 +4,15 @@
 - **Default:** `rstest`
 
 The name of the test project.
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+
+export default defineConfig({
+  name: 'node',
+});
+```
+
+When you define multiple test projects via [projects](/config/test/projects), it's recommended to give each project a unique name so that you can filter specific projects using the [--project](/guide/basic/test-filter#filter-by-project-name) option.
+
+If a project's name is not provided, Rstest will use the `name` field from the current project's `package.json`. If it does not exist, the folder name will be used instead.

website/docs/en/config/test/projects.mdx

@@ -7,6 +7,8 @@ An array of directories, config files, or glob patterns that define multiple tes
 
 `rstest` will run the tests for each project according to the configuration defined in each project, and the test results from all projects will be combined and displayed.
 
+You can filter the specified projects to run by using the [--project](/guide/basic/test-filter#filter-by-project-name) option.
+
 If there is no `projects` field, `rstest` will treat current directory as a single project.
 
 ```ts name='rstest.config.ts'

website/docs/en/guide/basic/cli.mdx

@@ -118,6 +118,7 @@ Rstest CLI provides several common options that can be used with all commands:
 | `-u, --update`                  | Update snapshot files, see [update](/config/test/update)                                                                                                          |
 | `--passWithNoTests`             | Allows the test suite to pass when no files are found, see [passWithNoTests](/config/test/passWithNoTests)                                                        |
 | `--printConsoleTrace`           | Print console traces when calling any console method, see [printConsoleTrace](/config/test/printConsoleTrace)                                                     |
+| `--project <name>`              | Only run tests for the specified project, see [Filter by project name](/guide/basic/test-filter#filter-by-project-name)                                           |
 | `--disableConsoleIntercept`     | Disable console intercept, see [disableConsoleIntercept](/config/test/disableConsoleIntercept)                                                                    |
 | `--slowTestThreshold <value>`   | The number of milliseconds after which a test or suite is considered slow, see [slowTestThreshold](/config/test/slowTestThreshold)                                |
 | `-t, --testNamePattern <value>` | Run only tests with a name that matches the regex, see [testNamePattern](/config/test/testNamePattern)                                                            |

website/docs/en/guide/basic/test-filter.mdx

@@ -80,6 +80,28 @@ rstest --testNamePattern login
 rstest -t login
 ```
 
+## Filter by project name
+
+Rstest supports defining multiple test projects via [projects](/config/test/projects). You can filter to run specific projects with the `--project` option.
+
+For example, to match projects whose [name](/config/test/name) is `@test/a` or `@test/b`:
+
+```bash
+rstest --project '@test/a' --project '@test/b'
+```
+
+You can also use wildcards to match project names:
+
+```bash
+rstest --project '@test/*'
+```
+
+You can exclude certain projects by negation:
+
+```bash
+rstest --project '!@test/a'
+```
+
 ## Combined filtering
 
 All filtering methods can be combined. For example:

website/docs/zh/config/test/name.mdx

@@ -4,3 +4,15 @@
 - **默认值：** `rstest`
 
 测试项目的名称。
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+
+export default defineConfig({
+  name: 'node',
+});
+```
+
+当你通过 [projects](/config/test/projects) 定义多个测试项目时，建议为每个项目指定唯一的名称，方便通过 [--project](/guide/basic/test-filter#根据项目名称过滤) 选项来过滤运行特定项目。
+
+如果 project 未提供名称，Rstest 将会使用当前项目的 `package.json` 中定义的 `name` 属性，如果不存在，则使用文件夹名称。