feat: support tags

docs/.vitepress/config.ts

@@ -473,6 +473,14 @@ export default ({ mode }: { mode: string }) => {
                 text: 'sequence',
                 link: '/config/sequence',
               },
+              {
+                text: 'tags',
+                link: '/config/tags',
+              },
+              {
+                text: 'strictTags',
+                link: '/config/stricttags',
+              },
               {
                 text: 'typecheck',
                 link: '/config/typecheck',
@@ -776,6 +784,10 @@ export default ({ mode }: { mode: string }) => {
                 text: 'Test Filtering',
                 link: '/guide/filtering',
               },
+              {
+                text: 'Test Tags',
+                link: '/guide/test-tags',
+              },
               {
                 text: 'Test Context',
                 link: '/guide/test-context',

docs/.vitepress/scripts/cli-generator.ts

@@ -42,6 +42,7 @@ const skipConfig = new Set([
   'browser.name',
   'browser.fileParallelism',
   'clearCache',
+  'tagsFilter',
 ])
 
 function resolveOptions(options: CLIOptions<any>, parentName?: string) {

docs/api/advanced/test-case.md

@@ -105,6 +105,7 @@ interface TaskOptions {
   readonly shuffle: boolean | undefined
   readonly retry: number | undefined
   readonly repeats: number | undefined
+  readonly tags: string[] | undefined
   readonly mode: 'run' | 'only' | 'skip' | 'todo'
 }
 ```

docs/api/advanced/test-specification.md

@@ -11,6 +11,7 @@ const specification = project.createSpecification(
     testLines: [20, 40],
     testNamePattern: /hello world/,
     testIds: ['1223128da3_0_0_0', '1223128da3_0_0'],
+    testTagsFilter: ['frontend and backend'],
   } // optional test filters
 )
 ```
@@ -82,6 +83,10 @@ A regexp that matches the name of the test in this module. This value will overr
 
 The ids of tasks inside of this specification to run.
 
+## testTagsFilter <Version>4.1.0</Version> {#testtagsfilter}
+
+The [tags filter](/guide/test-tags#syntax) that a test must pass in order to be included in the run. Multiple filters are treated as `AND`.
+
 ## toJSON
 
 ```ts

docs/api/advanced/test-suite.md

@@ -106,6 +106,7 @@ interface TaskOptions {
   readonly shuffle: boolean | undefined
   readonly retry: number | undefined
   readonly repeats: number | undefined
+  readonly tags: string[] | undefined
   readonly mode: 'run' | 'only' | 'skip' | 'todo'
 }
 ```

docs/api/index.md

@@ -29,9 +29,15 @@ interface TestOptions {
    * @default 0
    */
   repeats?: number
+  /**
+   * Custom tags of the test. Useful for filtering tests.
+   */
+  tags?: string[] | string
 }
 ```
 
+<!-- TODO: rewrite this into separate test files with options highlighted -->
+
 When a test function returns a promise, the runner will wait until it is resolved to collect async expectations. If the promise is rejected, the test will fail.
 
 ::: tip

docs/config/stricttags.md

@@ -0,0 +1,35 @@
+---
+title: strictTags | Config
+outline: deep
+---
+
+# strictTags <Version>4.1.0</Version> {#stricttags}
+
+- **Type:** `boolean`
+- **Default:** `true`
+- **CLI:** `--strict-tags`, `--no-strict-tags`
+
+Should Vitest throw an error if test has a [`tag`](/config/tags) that is not defined in the config to avoid silently doing something surprising due to mistyped names (applying the wrong configuration or skipping the test due to a `--tags-filter` flag).
+
+Note that Vitest will always throw an error if `--tags-filter` flag defines a tag not present in the config.
+
+For examle, this test will throw an error because the tag `fortnend` has a typo (it should be `frontend`):
+
+::: code-group
+```js [form.test.js]
+test('renders a form', { tags: ['fortnend'] }, () => {
+  // ...
+})
+```
+```js [vitest.config.js]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    tags: [
+      { name: 'frontend' },
+    ],
+  },
+})
+```
+:::

docs/config/tags.md

@@ -0,0 +1,198 @@
+---
+title: tags | Config
+outline: deep
+---
+
+# tags <Version>4.1.0</Version> {#tags}
+
+- **Type:** `TestTagDefinition[]`
+- **Default:** `[]`
+
+Defines all [available tags](/guide/test-tags) in your test project. By default, if test defines a name not listed here, Vitest will throw an error, but this can be configured via a [`strictTags`](/config/stricttags) option.
+
+If you are using [`projects`](/config/projects), they will inherit all global tags definitions automatically.
+
+Use [`--tags-filter`](/guide/test-tags#syntax) to filter tests by their tags.
+
+::: tip FILTERING
+You can use a wildcard (*) to match any number of symbols. To ignore a tag, add an exclamation mark (!) at the start of the tag.
+:::
+
+## name
+
+- **Type:** `string`
+- **Required:** `true`
+
+The name of the tag. This is what you use in the `tags` option in tests.
+
+```ts
+export default defineConfig({
+  test: {
+    tags: [
+      { name: 'unit' },
+      { name: 'e2e' },
+    ],
+  },
+})
+```
+
+::: tip
+If you are using TypeScript, you can enforce what tags are available by augmenting the `TestTags` type with a property that containst a union of strings (make sure this file is included by your `tsconfig`):
+
+```ts [vitest.shims.ts]
+import 'vitest'
+
+declare module 'vitest' {
+  interface TestTags {
+    tags:
+      | 'frontend'
+      | 'backend'
+      | 'db'
+      | 'flaky'
+  }
+}
+```
+:::
+
+## description
+
+- **Type:** `string`
+
+A human-readable description for the tag. This will be shown in UI and inside error messages when a tag is not found.
+
+```ts
+export default defineConfig({
+  test: {
+    tags: [
+      {
+        name: 'slow',
+        description: 'Tests that take a long time to run.',
+      },
+    ],
+  },
+})
+```
+
+## priority
+
+- **Type:** `number`
+- **Default:** `undefined`
+
+Priority for merging options when multiple tags with the same options are applied to a test. Lower number means higher priority (e.g., priority `1` takes precedence over priority `3`).
+
+```ts
+export default defineConfig({
+  test: {
+    tags: [
+      {
+        name: 'flaky',
+        timeout: 30_000,
+        priority: 1, // higher priority
+      },
+      {
+        name: 'db',
+        timeout: 60_000,
+        priority: 2, // lower priority
+      },
+    ],
+  },
+})
+```
+
+When a test has both tags, the `timeout` will be `30_000` because `flaky` has a higher priority.
+
+## Test Options
+
+Tags can define test options that will be applied to every test marked with the tag. These options are merged with the test's own options, with the test's options taking precedence.
+
+### timeout
+
+- **Type:** `number`
+
+Test timeout in milliseconds.
+
+### retry
+
+- **Type:** `number | { count?: number, delay?: number, condition?: RegExp }`
+
+Retry configuration for the test. If a number, specifies how many times to retry. If an object, allows fine-grained retry control.
+
+### repeats
+
+- **Type:** `number`
+
+How many times the test will run again.
+
+### concurrent
+
+- **Type:** `boolean`
+
+Whether suites and tests run concurrently.
+
+### sequential
+
+- **Type:** `boolean`
+
+Whether tests run sequentially.
+
+### skip
+
+- **Type:** `boolean`
+
+Whether the test should be skipped.
+
+### only
+
+- **Type:** `boolean`
+
+Should this test be the only one running in a suite.
+
+### todo
+
+- **Type:** `boolean`
+
+Whether the test should be skipped and marked as a todo.
+
+### fails
+
+- **Type:** `boolean`
+
+Whether the test is expected to fail. If it does, the test will pass, otherwise it will fail.
+
+## Example
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    tags: [
+      {
+        name: 'unit',
+        description: 'Unit tests.',
+      },
+      {
+        name: 'e2e',
+        description: 'End-to-end tests.',
+        timeout: 60_000,
+      },
+      {
+        name: 'flaky',
+        description: 'Flaky tests that need retries.',
+        retry: process.env.CI ? 3 : 0,
+        priority: 1,
+      },
+      {
+        name: 'slow',
+        description: 'Slow tests.',
+        timeout: 120_000,
+      },
+      {
+        name: 'skip-ci',
+        description: 'Tests to skip in CI.',
+        skip: !!process.env.CI,
+      },
+    ],
+  },
+})
+```

docs/guide/cli-generated.md

@@ -518,12 +518,26 @@ Default hook timeout in milliseconds (default: `10000`). Use `0` to disable time
 
 Stop test execution when given number of tests have failed (default: `0`)
 
-### retry
+### retry.count
 
-- **CLI:** `--retry <times>`
-- **Config:** [retry](/config/retry)
+- **CLI:** `--retry.count <times>`
+- **Config:** [retry.count](/config/retry#retry-count)
 
-Retry the test specific number of times if it fails (default: `0`)
+Number of times to retry a test if it fails (default: `0`)
+
+### retry.delay
+
+- **CLI:** `--retry.delay <ms>`
+- **Config:** [retry.delay](/config/retry#retry-delay)
+
+Delay in milliseconds between retry attempts (default: `0`)
+
+### retry.condition
+
+- **CLI:** `--retry.condition <pattern>`
+- **Config:** [retry.condition](/config/retry#retry-condition)
+
+Regex pattern to match error messages that should trigger a retry. Only errors matching this pattern will cause a retry (default: retry on all errors)
 
 ### diff.aAnnotation
 
@@ -798,6 +812,19 @@ Start Vitest without running tests. Tests will be running only on change. This o
 
 Delete all Vitest caches, including `experimental.fsModuleCache`, without running any tests. This will reduce the performance in the subsequent test run.
 
+### tagsFilter
+
+- **CLI:** `--tagsFilter <expression>`
+
+Run only tests with the specified tags. You can use logical operators `&&` (and), `||` (or) and `!` (not) to create complex expressions, see [Test Tags](/guide/test-tags#syntax) for more information.
+
+### strictTags
+
+- **CLI:** `--strictTags`
+- **Config:** [strictTags](/config/stricttags)
+
+Should Vitest throw an error if test has a tag that is not defined in the config. (default: `true`)
+
 ### experimental.fsModuleCache
 
 - **CLI:** `--experimental.fsModuleCache`

docs/guide/filtering.md

@@ -89,6 +89,24 @@ describe('suite', () => {
 })
 ```
 
+## Filtering Tags
+
+If your test defines a [tag](/guide/test-tags), you can filter your tests with a `--tags-filter` option:
+
+```ts
+test('renders a form', { tags: ['frontend'] }, () => {
+  // ...
+})
+
+test('calls an external API', { tags: ['backend'] }, () => {
+  // ...
+})
+```
+
+```shell
+vitest --tags-filter=frontend
+```
+
 ## Selecting Suites and Tests to Run
 
 Use `.only` to only run certain suites or tests