feat: support describe.sequential (#3771)

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

Author: fenghan34

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)
+ })
+ })
+})