# API Reference

The following types are used in the type signatures below

```ts
type Awaitable<T> = T | PromiseLike<T>
type TestFunction = () => Awaitable<void>
```

## test

`test` defines a set of related expectations. Default timeout for tests is 5 seconds, and can be configured globally with [testTimeout](../config/#testtimeout).

**Type:** `(name: string, fn: TestFunction, timeout?: number) => void`
**Alias:** `it`

```ts
import { test, expect } from 'vitest'

test('should work as expected', () => {
  expect(Math.sqrt(4)).toBe(2);
})
```

### test.skip

Use `.skip` to avoid running certain tests

**Type:** `(name: string, fn: TestFunction, timeout?: number) => void`

```ts
test.skip("skipped test", () => {
  // Test skipped, no error
  assert.equal(Math.sqrt(4), 3);
});
```

### test.only

Use `.only` to only run certain tests in a given suite 

**Type:** `(name: string, fn: TestFunction, timeout?: number) => void`

```ts
it.only("test", () => {
    // Only this test (and others marked with only) are run
    assert.equal(Math.sqrt(4), 2);
  });
});
```

### test.concurrent

`.concurrent` marks consecutive tests to be run them in parallel. It receives the test name, an async function with the tests to collect, and an optional timeout (in milliseconds).

**Type:** `(name: string, fn: TestFunction, timeout?: number) => void`

```ts
// The two tests marked with concurrent will be run in parallel
describe("suite", () => {
  test("serial test", async() => { /* ... */ });
  test.concurrent("concurrent test 1", async() => { /* ... */ });
  test.concurrent("concurrent test 2", async() => { /* ... */ });
});
```

`.skip`, `.only`, and `.todo` works with concurrent tests. All the following combinations are valid:

```ts
test.concurrent(...)
test.skip.concurrent(...), test.concurrent.skip(...)
test.only.concurrent(...), test.concurrent.only(...)
test.todo.concurrent(...), test.concurrent.todo(...)
```

### test.todo

Use `.todo` to stub tests to be implemented later

**Type:** `(name: string) => void`

```ts
// An entry will be shown in the report for this test
test.todo("unimplemented test");
```

## describe

Defines a new suite, as a set of related tests and nested suites. A suite lets you organize your tests so reports are more clear.

### describe.skip

Use `.skip` in a suite to avoid avoid running it

**Type:** `(name: string, fn: TestFunction, timeout?: number) => void`

```ts
describe.skip("skipped suite", () => {
  test("sqrt", () => {
    // Suite skipped, no error
    assert.equal(Math.sqrt(4), 3);
  });
});
```

### describe.only

Use `.only` to only run certain suites

**Type:** `(name: string, fn: TestFunction, timeout?: number) => void`

```ts
// Only this suite (and others marked with only) are run
describe.only("suite", () => {
  test("sqrt", () => {
    assert.equal(Math.sqrt(4), 3);
  });
});
```

### describe.concurrent

`.concurrent` in a suite marks every tests as concurrent

**Type:** `(name: string, fn: TestFunction, timeout?: number) => void`

```ts
// All tests within this suite will be run in parallel
describe.concurrent("suite", () => {
  test("concurrent test 1", async() => { /* ... */ });
  test("concurrent test 2", async() => { /* ... */ });
  test.concurrent("concurrent test 3", async() => { /* ... */ });
});
```

`.skip`, `.only`, and `.todo` works with concurrent suites. All the following combinations are valid:

```ts
describe.concurrent(...)
describe.skip.concurrent(...), describe.concurrent.skip(...)
describe.only.concurrent(...), describe.concurrent.only(...)
describe.todo.concurrent(...), describe.concurrent.todo(...)
```

### describe.todo

Use `.todo` to stub suites to be implemented later

**Type:** `(name: string) => void`

```ts
// An entry will be shown in the report for this suite
describe.todo("unimplemented suite");
```