feat: support describe.sequential (#3771)

Co-authored-by: Anjorin Damilare <damilareanjorin1@gmail.com>

docs/api/index.md

@@ -639,6 +639,24 @@ When running concurrent tests, Snapshots and Assertions must use `expect` from t
 You cannot use this syntax, when using Vitest as [type checker](/guide/testing-types).
 :::
 
+### describe.sequential
+
+- **Type:** `(name: string | Function, fn: TestFunction, options?: number | TestOptions) => void`
+
+  `describe.sequential` in a suite marks every test as sequential. This is useful if you want to run tests in sequential within `describe.concurrent` or with the `--sequence.concurrent` command option.
+
+  ```ts
+  describe.concurrent('suite', () => {
+    test('concurrent test 1', async () => { /* ... */ })
+    test('concurrent test 2', async () => { /* ... */ })
+
+    describe.sequential('', () => {
+      test('sequential test 1', async () => { /* ... */ })
+      test('sequential test 2', async () => { /* ... */ })
+    })
+  })
+  ```
+
 ### describe.shuffle
 
 - **Type:** `(name: string | Function, fn: TestFunction, options?: number | TestOptions) => void`

packages/runner/src/suite.ts

@@ -53,7 +53,7 @@ export function createSuiteHooks() {
 }
 
 // implementations
-function createSuiteCollector(name: string, factory: SuiteFactory = () => { }, mode: RunMode, concurrent?: boolean, shuffle?: boolean, each?: boolean, suiteOptions?: TestOptions) {
+function createSuiteCollector(name: string, factory: SuiteFactory = () => { }, mode: RunMode, concurrent?: boolean, sequential?: boolean, shuffle?: boolean, each?: boolean, suiteOptions?: TestOptions) {
   const tasks: (Test | TaskCustom | Suite | SuiteCollector)[] = []
   const factoryQueue: (Test | Suite | SuiteCollector)[] = []
 
@@ -84,7 +84,7 @@ function createSuiteCollector(name: string, factory: SuiteFactory = () => { }, m
       meta: Object.create(null),
     } as Omit<Test, 'context'> as Test
 
-    if (this.concurrent || concurrent || runner.config.sequence.concurrent)
+    if (this.concurrent || (!sequential && (concurrent || runner.config.sequence.concurrent)))
       test.concurrent = true
     if (shuffle)
       test.shuffle = true
@@ -198,7 +198,7 @@ function createSuite() {
     if (currentSuite?.options)
       options = { ...currentSuite.options, ...options }
 
-    return createSuiteCollector(formatName(name), factory, mode, this.concurrent, this.shuffle, this.each, options)
+    return createSuiteCollector(formatName(name), factory, mode, this.concurrent, this.sequence, this.shuffle, this.each, options)
   }
 
   suiteFn.each = function<T>(this: { withContext: () => SuiteAPI; setContext: (key: string, value: boolean | undefined) => SuiteAPI }, cases: ReadonlyArray<T>, ...args: any[]) {
@@ -226,14 +226,14 @@ function createSuite() {
   suiteFn.runIf = (condition: any) => (condition ? suite : suite.skip) as SuiteAPI
 
   return createChainable(
-    ['concurrent', 'shuffle', 'skip', 'only', 'todo'],
+    ['concurrent', 'sequential', 'shuffle', 'skip', 'only', 'todo'],
     suiteFn,
   ) as unknown as SuiteAPI
 }
 
 function createTest(fn: (
   (
-    this: Record<'concurrent' | 'skip' | 'only' | 'todo' | 'fails' | 'each', boolean | undefined> & { fixtures?: FixtureItem[] },
+    this: Record<'concurrent' | 'sequential' | 'skip' | 'only' | 'todo' | 'fails' | 'each', boolean | undefined> & { fixtures?: FixtureItem[] },
     title: string,
     fn?: TestFunction,
     options?: number | TestOptions

packages/runner/src/types/tasks.ts

@@ -199,7 +199,7 @@ export type Fixtures<T extends Record<string, any>, ExtraContext = {}> = {
 }
 
 type ChainableSuiteAPI<ExtraContext = {}> = ChainableFunction<
-  'concurrent' | 'only' | 'skip' | 'todo' | 'shuffle',
+  'concurrent' | 'sequential' | 'only' | 'skip' | 'todo' | 'shuffle',
   [name: string | Function, factory?: SuiteFactory<ExtraContext>, options?: number | TestOptions],
   SuiteCollector<ExtraContext>,
   {

test/core/test/sequential.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'vitest'
+
+const delay = (timeout: number) => new Promise(resolve => setTimeout(resolve, timeout))
+
+let count = 0
+
+describe.concurrent('', () => {
+  describe.sequential('', () => {
+    test('should pass', async ({ task }) => {
+      await delay(50)
+      expect(task.concurrent).toBeFalsy()
+      expect(++count).toBe(1)
+    })
+
+    test('should pass', ({ task }) => {
+      expect(task.concurrent).toBeFalsy()
+      expect(++count).toBe(2)
+    })
+  })
+})