feat: add test.sequential() api (#4512)

docs/api/index.md

@@ -224,6 +224,30 @@ test.concurrent('test 2', async ({ expect }) => {
 You cannot use this syntax, when using Vitest as [type checker](/guide/testing-types).
 :::
 
+### test.sequential
+
+- **Type:** `(name: string | Function, fn: TestFunction, timeout?: number) => void`
+
+`test.sequential` marks a test as sequential. This is useful if you want to run tests in sequence within `describe.concurrent` or with the `--sequence.concurrent` command option.
+
+```ts
+// with config option { sequence: { concurrent: true } }
+test('concurrent test 1', async () => { /* ... */ })
+test('concurrent test 2', async () => { /* ... */ })
+
+test.sequential('sequential test 1', async () => { /* ... */ })
+test.sequential('sequential test 2', async () => { /* ... */ })
+
+// within concurrent suite
+describe.concurrent('suite', () => {
+  test('concurrent test 1', async () => { /* ... */ })
+  test('concurrent test 2', async () => { /* ... */ })
+
+  test.sequential('sequential test 1', async () => { /* ... */ })
+  test.sequential('sequential test 2', async () => { /* ... */ })
+})
+```
+
 ### test.todo
 
 - **Type:** `(name: string | Function) => void`

packages/runner/src/suite.ts

@@ -280,7 +280,7 @@ export function createTaskCollector(
   }
 
   const _test = createChainable(
-    ['concurrent', 'skip', 'only', 'todo', 'fails'],
+    ['concurrent', 'sequential', 'skip', 'only', 'todo', 'fails'],
     taskFn,
   ) as CustomAPI
 

packages/runner/src/types/tasks.ts

@@ -150,7 +150,7 @@ interface TestEachFunction {
 }
 
 type ChainableTestAPI<ExtraContext = {}> = ChainableFunction<
-  'concurrent' | 'only' | 'skip' | 'todo' | 'fails',
+  'concurrent' | 'sequential' | 'only' | 'skip' | 'todo' | 'fails',
   [name: string | Function, fn?: TestFunction<ExtraContext>, options?: number | TestOptions],
   void,
   {

test/core/test/sequential-sequence-concurrent.test.ts

@@ -22,3 +22,14 @@ describe.sequential('running sequential suite when sequence.concurrent is true',
     expect(++count).toBe(2)
   })
 })
+
+test.sequential('third test completes third', async ({ task }) => {
+  await delay(50)
+  expect(task.concurrent).toBeFalsy()
+  expect(++count).toBe(3)
+})
+
+test.sequential('fourth test completes fourth', ({ task }) => {
+  expect(task.concurrent).toBeFalsy()
+  expect(++count).toBe(4)
+})

test/core/test/sequential.test.ts

@@ -41,6 +41,17 @@ function assertConcurrent() {
     expect(task.concurrent).toBe(true)
     expect(++count).toBe(1)
   })
+
+  test.sequential('third test completes third', async ({ task }) => {
+    await delay(50)
+    expect(task.concurrent).toBeFalsy()
+    expect(++count).toBe(3)
+  })
+
+  test.sequential('fourth test completes fourth', ({ task }) => {
+    expect(task.concurrent).toBeFalsy()
+    expect(++count).toBe(4)
+  })
 }
 
 assertSequential()