Japa

https://japa.dev/docs
Admin
Japa is a simple yet powerful testing framework for Node.js that enables testing backend...
Tokens:109,917
Snippets:1,280
Trust Score:7.5
Update:3 days ago
Show doc for...
Tokens:
Raw
### Install browser client plugin

Source: https://japa.dev/docs/plugins/browser-client

Install the @japa/browser-client package.

```bash
npm i -D @japa/browser-client
```

--------------------------------

### setup

Source: https://japa.dev/docs/reference/test

Defines the setup hook for the test, executed before the test.

```APIDOC
## setup

### Description
Define the setup hook for the test.

### Method
setup

### Usage
```
test('add two numbers', () => {

})

.setup(async () => {

  // executed before the test

})
```

### See Also
Hooks
```

--------------------------------

### Install @japa/api-client

Source: https://japa.dev/docs/plugins/api-client

Install the package from the npm registry.

```bash
npm i -D @japa/api-client
```

--------------------------------

### Install @japa/snapshot

Source: https://japa.dev/docs/plugins/snapshot

Install the snapshot plugin via npm.

```bash
npm i -D @japa/snapshot
```

--------------------------------

### Install nyc

Source: https://japa.dev/docs/coverage

Install the nyc coverage tool as a development dependency.

```bash
npm i -D nyc
```

--------------------------------

### Define setup hook with .setup()

Source: https://japa.dev/docs/reference/test

Defines a setup hook that executes before the test runs.

```javascript
test('add two numbers', () => {

})

.setup(async () => {

  // executed before the test

})
```

--------------------------------

### Install @japa/file-system

Source: https://japa.dev/docs/plugins/file-system

Install the plugin via npm as a development dependency.

```bash
npm i -D @japa/file-system
```

--------------------------------

### Install c8

Source: https://japa.dev/docs/coverage

Install the c8 coverage tool as a development dependency.

```bash
npm i -D c8
```

--------------------------------

### Install Assert Plugin

Source: https://japa.dev/docs/plugins/assert

Install the @japa/assert package using npm.

```bash
npm i -D @japa/assert
```

--------------------------------

### Installation

Source: https://japa.dev/docs/plugins/api-client

Install the @japa/api-client package from npm as a dev dependency.

```APIDOC
## Installation

### Description
Install the @japa/api-client package from the npm registry.

### Command
npm i -D @japa/api-client
```

--------------------------------

### Install @japa/expect

Source: https://japa.dev/docs/plugins/expect

Install the package from the npm registry as a development dependency.

```bash
npm i -D @japa/expect
```

--------------------------------

### Install peer dependencies

Source: https://japa.dev/docs/plugins/browser-client

Install the required peer dependencies for the browser client plugin.

```bash
npm i -D @japa/assert playwright
```

--------------------------------

### Installation

Source: https://japa.dev/docs/plugins/assert

Install the @japa/assert package via npm and register it as a plugin in the test entry point.

```APIDOC
## Installation

### Install Package
```bash
npm i -D @japa/assert
```

### Register Plugin
```javascript
import { assert } from '@japa/assert'
import { configure } from '@japa/runner'

configure({
  files: ['tests/**/*.spec.js'],
  plugins: [assert()]
})
```

### Access Assert in Test
```javascript
test('add two numbers', ({ assert }) => {
  assert.equal(2 + 2, 4)
})
```
```

--------------------------------

### Install @japa/expect-type

Source: https://japa.dev/docs/plugins/expect-type

Install the package from the npm registry as a development dependency.

```bash
npm i -D @japa/expect-type
```

--------------------------------

### Install @japa/openapi-assertions package

Source: https://japa.dev/docs/plugins/openapi-assertions

Install the plugin from the npm registry as a dev dependency.

```bash
npm i -D @japa/openapi-assertions
```

--------------------------------

### Organize tests by resource, action, and scenario

Source: https://japa.dev/docs/filtering-tests

Example directory structure for organizing tests.

```text
.
├── polls
│   └── list
│       ├── guest.spec.js
│       └── logged_in.spec.js
```

--------------------------------

### Returning cleanup functions from setup hooks

Source: https://japa.dev/docs/lifecycle-hooks

Return an async function from a setup hook to clean up state created by that specific hook.

```typescript
import { test } from '@japa/runner'

test.group('Users.create', (group) => {
  group.each.setup(async () => {
    await createTables()
    // 👇 Cleanup function
    return async () => await dropTables()
  })

  test('create a new user', () => {
  })
})
```

--------------------------------

### assert.isAbove examples

Source: https://japa.dev/docs/plugins/assert

Shows passing examples for assert.isAbove. Supports numbers, dates, and luxon datetime objects. The first example passes because 5 is above 2, the second passes because the date 2020-12-20 is above 2020-12-18.

```javascript
assert.isAbove(5, 2) // passes

assert.isAbove(new Date('2020 12 20'), new Date('2020 12 18')) // passes
```

--------------------------------

### Organize tests for single-scenario actions

Source: https://japa.dev/docs/filtering-tests

Example directory structure for a top-level test file.

```text
.
├── users
    └── register.spec.js
```

--------------------------------

### assert.isBelow examples

Source: https://japa.dev/docs/plugins/assert

Shows passing examples for assert.isBelow. Supports numbers, dates, and luxon datetime objects. The first example passes because 2 is below 5, the second passes because the date 2020-12-20 is below 2020-12-24.

```javascript
assert.isBelow(2, 5) // passes

assert.isBelow(new Date('2020 12 20'), new Date('2020 12 24')) // passes
```

--------------------------------

### Example of teardown hook failure

Source: https://japa.dev/docs/lifecycle-hooks

This example demonstrates how teardown hooks can fail if a setup hook throws an error, as the teardown will attempt to access undefined variables.

```typescript
test.group('Users.create', (group) => {
  let browser = null

  group.each.setup(async () => {
    throw new Error('This hook failed due to some reason')
  })

  group.each.setup(async () => {
    browser = await chromium.launch()
  })

  group.each.teardown(async () => {
    browser.close()
  })

  test('create a new user', () => {
  })
})
```

--------------------------------

### Install concurrently package

Source: https://japa.dev/docs/test-suites

Install the concurrently package to enable running multiple test suites in parallel.

```bash
npm i -D concurrently
```

--------------------------------

### Configure browserClient plugin

Source: https://japa.dev/docs/plugins/browser-client

Example of registering the browserClient plugin with various options in the plugins array.

```javascript
plugins: [
  browserClient({
    runInSuites: ['browser'],
    contextOptions: {},
    tracing: {
      enabled: false,
      event: 'onError',
      cleanOutputDirectory: true,
      outputDirectory: join(__dirname, '..')
    }
  })
]
```

--------------------------------

### Write a browser test

Source: https://japa.dev/docs/plugins/browser-client

Example of a test file located in tests/browser using the visit helper to navigate and assert page content.

```javascript
import { test } from '@japa/runner'

test('has docs for browser client', async ({ visit }) => {
  const page = await visit('https://japa.dev/docs')
  await page.getByRole('link', { name: 'Browser client' }).click()

  /**
   * Assertions
   */
  await page.assertPath('/docs/plugins/browser-client')
  await page.assertTextContains('body', 'Browser client')
})
```

--------------------------------

### assert.sealed and assert.isSealed examples

Source: https://japa.dev/docs/plugins/assert

Shows passing and failing examples for assert.sealed and assert.isSealed. Both methods assert that an object is sealed. The first example passes because Object.seal({}) is sealed, the second fails because a plain object is not sealed.

```javascript
assert.sealed(Object.seal({})) // passes

assert.sealed({}) // fails



assert.isSealed(Object.seal({})) // passes

assert.isSealed({}) // fails
```

--------------------------------

### Configure npm scripts for browser tests

Source: https://japa.dev/docs/plugins/browser-client

Example configuration for package.json to run browser-specific tests via npm scripts.

```json
{

  "test:firefox": "node bin/test.js --browser=firefox",

  "test:chromium": "node bin/test.js --browser=chromium",

  "test": "npm run test:firefox && npm run test:chromium"

}
```

--------------------------------

### assert.notSealed and assert.isNotSealed examples

Source: https://japa.dev/docs/plugins/assert

Shows passing and failing examples for assert.notSealed and assert.isNotSealed. Both methods assert that an object is not sealed. The first example passes because a plain object is not sealed, the second fails because Object.seal({}) is sealed.

```javascript
assert.notSealed({}) // passes

assert.notSealed(Object.seal({})) // fails



assert.isNotSealed({}) // passes

assert.isNotSealed(Object.seal({})) // fails
```

--------------------------------

### assert.empty and assert.isEmpty example

Source: https://japa.dev/docs/plugins/assert

Shows how to use assert.empty and assert.isEmpty to assert that a value is empty. Both methods are shown with arrays and strings.

```javascript
assert.empty([]) // passes
assert.empty('') // passes

assert.isEmpty([]) // passes
assert.isEmpty('') // passes
```

--------------------------------

### Configure redirects

Source: https://japa.dev/docs/plugins/api-client

Configures the number of redirects to follow. The second example shows how to retrieve redirect links from the response.

```javascript
// follow two redirects from the server

request.redirects(2)
```

```javascript
const response = await request.redirects(2)

console.log(response.redirects())
```

--------------------------------

### Write a basic test in tests/example.spec.js

Source: https://japa.dev/docs/installation

Example of defining a test using the @japa/runner package and asserting a result using TestContext.

```javascript
import { test } from '@japa/runner'

function sum(a, b) {
  return a + b
}

test('add two numbers', ({ assert }) => {
  assert.equal(sum(2, 2), 4)
})
```

--------------------------------

### Example snapshot file content

Source: https://japa.dev/docs/plugins/snapshot

The generated snapshot file content in tests/__snapshots__/my-test.spec.ts.cjs.

```javascript
exports['match snapshot 1'] = `"1"`
```

--------------------------------

### assert.lengthOf example

Source: https://japa.dev/docs/plugins/assert

Shows how to use assert.lengthOf to check the length of an array, map, or set. The examples check an array of three elements, a map with two entries, and a string with 11 characters.

```javascript
assert.lengthOf([1, 2, 3], 3)
assert.lengthOf(new Map([[1],[2]]), 2)
assert.lengthOf('hello world', 11)
```

--------------------------------

### Get response redirects

Source: https://japa.dev/docs/plugins/api-client

Returns an array of URLs for redirects followed by the request.

```javascript
response.redirects()
```

--------------------------------

### Registering test lifecycle hooks

Source: https://japa.dev/docs/lifecycle-hooks

Use the setup and teardown methods on a test to execute code before and after the test runs.

```typescript
import { test } from '@japa/runner'

test('add two numbers', () => {
  console.log('executed in the test')
})
.setup(() => {
  console.log('executed before the test')
})
.teardown(() => {
  console.log('executed after the test')
})
```

--------------------------------

### Callback-based async test

Source: https://japa.dev/docs/testing-async-code

Example of a test using a callback that requires .waitForDone().

```javascript
test('generate pdf', (ctx, done) => {

  pdf

    .create(html, options)

    .toFile('./businesscard.pdf', function(error, res) {

      if (error) {

        done(error)

      } else {

        done()

      }

    })

})

.waitForDone()
```

--------------------------------

### Defining global lifecycle hooks

Source: https://japa.dev/docs/plugins/api-client

Use the ApiClient class to define setup and teardown hooks that execute before and after every request.

```typescript
import { ApiClient } from '@japa/api-client'

ApiClient.setup(async (request) => {
  // executed before each request
})

ApiClient.teardown(async (response) => {
  // executed after each request
})
```

--------------------------------

### Create test directory and file

Source: https://japa.dev/docs/installation

Commands to create the required tests directory and an initial test file.

```bash
mkdir tests

touch tests/example.spec.js
```

--------------------------------

### Rewriting teardown with cleanup functions

Source: https://japa.dev/docs/lifecycle-hooks

Using a cleanup function ensures that if a setup hook fails, the corresponding cleanup is not executed, preventing errors.

```typescript
test.group('Users.create', (group) => {
  let browser = null

  group.each.setup(async () => {
    throw new Error('This hook failed due to some reason')
  })

  group.each.setup(async () => {
    browser = await chromium.launch()
    return () => browser.close()
  })

  test('create a new user', () => {
  })
})
```

--------------------------------

### client.get(endpoint)

Source: https://japa.dev/docs/plugins/api-client

Make a GET request to the specified endpoint. Returns a Response instance.

```APIDOC
## client.get(endpoint)

### Description
Performs an HTTP GET request to the given endpoint.

### Method
GET

### Endpoint
{baseUrl}{endpoint}

### Parameters
#### Path Parameters
- **endpoint** (string) - Required - The request endpoint path.

### Response
Returns a Response instance with methods: status(), body(), method(), headers().
```

--------------------------------

### Defining lifecycle hooks on a request

Source: https://japa.dev/docs/plugins/api-client

Define hooks for an individual request using the setup method on the client instance.

```typescript
test('get /users', async ({ client }) => {
  const response = await client
    .get('/posts')
    .setup(async () => {
      await createDummyPosts(20)
      return () => clearDatabase()
    })

  response.assertStatus(200)
})
```

--------------------------------

### ApiClient.setup and ApiClient.teardown

Source: https://japa.dev/docs/plugins/api-client

Define global lifecycle hooks executed before each request and after each response.

```APIDOC
## ApiClient.setup(callback)

### Description
Registers a global hook executed before each request.

### Method
setup

### Parameters
- **callback** (Function) - Required - Async function receiving the request object.

### Example
```js
ApiClient.setup(async (request) => {
  // executed before each request
})
```

## ApiClient.teardown(callback)

### Description
Registers a global hook executed after each response.

### Method
teardown

### Parameters
- **callback** (Function) - Required - Async function receiving the response object.

### Example
```js
ApiClient.teardown(async (response) => {
  // executed after each request
})
```
```

--------------------------------

### Define suite lifecycle hooks

Source: https://japa.dev/docs/test-suites

Register setup and teardown hooks within the suite configuration object using the suite instance.

```javascript
configure({
  suites: [
    {
      name: 'functional',
      files: ['tests/functional/**/*.spec.js'],
      configure(suite) {
        suite.setup(() => {
          server = createServer(handler)
          server.start()

          return () => server.close()
        })
      },
    }
  ]
})
```

--------------------------------

### Console output for group lifecycle hooks

Source: https://japa.dev/docs/lifecycle-hooks

The expected console output when running the group-level lifecycle hook example.

```text
executed before all the test

TEST 1 - executed in the test
TEST 2 - executed in the test

executed after all the test
```

--------------------------------

### Initialize Japa with npm

Source: https://japa.dev/docs/installation

Run this command to initialize Japa in an existing Node.js project using npm.

```bash
npm init japa@latest .
```

--------------------------------

### assert.throws example

Source: https://japa.dev/docs/plugins/assert

Shows how to use assert.throws to expect an exception. The function foo throws an Error with message 'blow up'. The first three assertions pass, the last one fails because the message does not match.

```javascript
function foo() { throw new Error('blow up') }

assert.throws(foo) // passes
assert.throws(foo, Error) // passes
assert.throws(foo, 'blow up') // passes
assert.throws(foo, 'failed') // fails
```

--------------------------------

### Run Japa tests with Node.js, Bun, and TypeScript

Source: https://japa.dev/docs/introduction

Commands to run Japa tests using different runtimes: Node.js, Bun, TypeScript with native Node.js support, and TypeScript with ts-exec. Choose the command that matches your project setup.

```bash
# Node.js

node bin/tests.js

# Bun

bun bin/tests.js

# TypeScript with native Node.js support

node bin/test.ts

# TypeScript with ts-exec (install the package separately)

npx @poppinss/ts-exec bin/tests.js
```

--------------------------------

### Request.setup

Source: https://japa.dev/docs/plugins/api-client

Define a lifecycle hook for an individual request, executed before the request is sent.

```APIDOC
## Request.setup(callback)

### Description
Registers a hook executed before the request is sent. The callback can return a cleanup function executed after the response.

### Method
setup

### Parameters
- **callback** (Function) - Required - Async function. May return a cleanup function.

### Example
```js
const response = await client
  .get('/posts')
  .setup(async () => {
    await createDummyPosts(20)
    return () => clearDatabase()
  })
```
```

--------------------------------

### GitHub Actions workflow for parallel shards

Source: https://japa.dev/docs/filtering-tests

Example of a GitHub Actions workflow that splits tests into four parallel jobs using a matrix. Each job runs a shard with the --shard flag.

```yaml
name: test

on: [push, pull_request]



jobs:

  test:

    runs-on: ubuntu-latest

    strategy:

      fail-fast: false

      matrix:

        shard: [1, 2, 3, 4]

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: 24

          cache: npm

      - run: npm ci

      - run: node bin/test.js --shard=${{ matrix.shard }}/4
```

--------------------------------

### Example of discouraged nested test groups

Source: https://japa.dev/docs/grouping-tests

An example demonstrating the nesting of test groups, which is not supported by Japa.

```typescript
let user



test.group('A top level group', (group) => {

  group.setup(() => {

    user = await getUserForTesting()

  })

  

  test.group('a nested group', () => {

    test.group('another level of testing', () => {

      test('use the user in the test', () => {

        console.log(user)

      })

    })

  })

})
```

--------------------------------

### fs.create

Source: https://japa.dev/docs/plugins/file-system

Create a file at a given location. Missing directories are created automatically.

```APIDOC
## fs.create

### Description
Create a file at a given location. The missing directories will be created automatically.

### Method
fs.create

### Parameters
#### Arguments
- **filePath** (String) - Required - Path to the file to create.
- **contents** (String) - Required - Contents of the file.
- **options** (WriteFileOptions) - Optional - Write options.

### Request Example
```js
test('read rc file', async ({ fs }) => {
  await fs.create('rc.json', JSON.stringify({ foo: 'bar' }))
})
```

### Response
No response body.
```

--------------------------------

### assert.isNull usage example

Source: https://japa.dev/docs/plugins/assert

Asserts that the value is null. The example shows that null passes, while true, false, and 'foo' fail.

```javascript
assert.isNull(null) // passes

assert.isNull(true) // fails

assert.isNull(false) // fails

assert.isNull('foo') // fails
```

--------------------------------

### fs.create

Source: https://japa.dev/docs/plugins/file-system

Creates a file at a given location, automatically creating any missing directories.

```javascript
test('read rc file', async ({ fs }) => {

  await fs.create('rc.json', JSON.stringify({

    foo: 'bar'

  }))

})
```

--------------------------------

### Configure Japa entry point

Source: https://japa.dev/docs/installation

The bin/test(.js|.ts) file configures Japa, registers plugins, and executes the test runner.

```javascript
import { assert } from '@japa/assert'

import { apiClient } from '@japa/api-client'

import { expectTypeOf } from '@japa/expect-type'

import { configure, processCLIArgs, run } from '@japa/runner'



processCLIArgs(process.argv.splice(2))



configure({

  files: ['tests/**/*.spec.js'],

  plugins: [

    assert(),

    expectTypeOf(),

  ],

})



run()
```

--------------------------------

### assert.isNotNull usage example

Source: https://japa.dev/docs/plugins/assert

Asserts that the value is anything but not null. The example shows that null fails, while true, false, and 'foo' pass.

```javascript
assert.isNotNull(null) // fails

assert.isNotNull(true) // passes

assert.isNotNull(false) // passes

assert.isNotNull('foo') // passes
```

--------------------------------

### Initialize Japa with yarn

Source: https://japa.dev/docs/installation

Run this command to initialize Japa in an existing Node.js project using yarn.

```bash
yarn create japa@latest .
```

--------------------------------

### assert.isNotFunction usage example

Source: https://japa.dev/docs/plugins/assert

Asserts that the value is not a function. The example shows that non-function values like {} and null pass, while a function fails.

```javascript
assert.isNotFunction({}) // passes

assert.isNotFunction(null) // passes

assert.isNotFunction(() => {}) // fails
```

--------------------------------

### assert.isNumber usage example

Source: https://japa.dev/docs/plugins/assert

Asserts that the value is a valid number. The example shows that 1 and new Number('1') pass, while '1' fails.

```javascript
assert.isNumber(1) // passes

assert.isNumber(new Number('1')) // passes

assert.isNumber('1') // fails
```

--------------------------------

### assert.isNaN usage example

Source: https://japa.dev/docs/plugins/assert

Asserts that the value is NaN. The example shows that NaN and Number('hello') pass, while true, false, and null fail.

```javascript
assert.isNaN(NaN) // passes

assert.isNaN(Number('hello')) // passes

assert.isNaN(true) // fails

assert.isNaN(false) // fails

assert.isNaN(null) // fails
```

--------------------------------

### Initialize Japa with pnpm

Source: https://japa.dev/docs/installation

Run this command to initialize Japa in an existing Node.js project using pnpm.

```bash
pnpm create japa@latest .
```

--------------------------------

### assert.isNotNaN usage example

Source: https://japa.dev/docs/plugins/assert

Asserts that the value is anything but not NaN. The example shows that NaN and Number('hello') fail, while true, false, and null pass.

```javascript
assert.isNotNaN(NaN) // fails

assert.isNotNaN(Number('hello')) // fails

assert.isNotNaN(true) // passes

assert.isNotNaN(false) // passes

assert.isNotNaN(null) // passes
```

--------------------------------

### Dataset-driven test example

Source: https://japa.dev/docs/introduction

Example of a dataset-driven test in Japa that validates an email function against multiple inputs. The test uses the 'with' method to provide an array of email addresses and asserts that each one is valid.

```javascript
test('validate email')

 .with([

    'some+user@gmail.com',

    'some.user@gmail.com',

    'email@123.123.123.123'

  ])

  .run(({ assert }, email) => {

    assert.isTrue(validateEmail(email))

  })
```

--------------------------------

### fs.stats

Source: https://japa.dev/docs/plugins/file-system

Get `fs.Stats` for a file by its location.

```APIDOC
## fs.stats

### Description
Get `fs.Stats` for a file by its location.

### Method
fs.stats

### Parameters
#### Arguments
- **filePath** (String) - Required - Path to the file.

### Request Example
```js
test('read rc file', async ({ fs }) => {
  const stats = await fs.stats('rc.json')
})
```

### Response
Returns an `fs.Stats` object for the file.
```

--------------------------------

### Get response status

Source: https://japa.dev/docs/plugins/api-client

Returns the response status code.

```javascript
response.status()
```

--------------------------------

### Run tests by folder and filename pattern

Source: https://japa.dev/docs/filtering-tests

Run tests from any filename ending with 'register' inside the users folder.

```bash
node bin/test.js --files="users/register"
```

--------------------------------

### Configure tracing options

Source: https://japa.dev/docs/plugins/browser-client

Sets up tracing configuration for generating test traces.

```javascript
import { join } from 'path'

browserClient({
  tracing: {
    enabled: false, // can be enabled using --trace flag
    event: 'onError',
    cleanOutputDirectory: true,
    outputDirectory: join(__dirname, '../tests/traces')
  }
})
```

--------------------------------

### Get all response headers

Source: https://japa.dev/docs/plugins/api-client

Returns all response headers as an object.

```javascript
response.headers()
```

--------------------------------

### fs.mkdir

Source: https://japa.dev/docs/plugins/file-system

Create a directory recursively inside the root of the file system.

```APIDOC
## fs.mkdir

### Description
Create a directory recursively inside the root of the file system.

### Method
fs.mkdir

### Parameters
#### Arguments
- **dirPath** (String) - Required - Path to the directory to create.

### Request Example
```js
test('copy files', async ({ fs }) => {
  await fs.mkdir('make/controller')
})
```

### Response
No response body.
```

--------------------------------

### Get response cookie

Source: https://japa.dev/docs/plugins/api-client

Retrieves the value for a specific cookie.

```javascript
const value = response.cookie('cart_value')
```

--------------------------------

### Get response status type

Source: https://japa.dev/docs/plugins/api-client

Returns the class of the status code.

```javascript
response.status() // 301

response.statusType() // 3



response.status() // 404

response.statusType() // 4



response.status() // 202

response.statusType() // 2
```

--------------------------------

### Run tests by tag

Source: https://japa.dev/docs/filtering-tests

Run tests with the @payment_gateway tag.

```bash
node bin/test.js --tags="@payment_gateway"
```

--------------------------------

### Get response content type

Source: https://japa.dev/docs/plugins/api-client

Returns the response content type.

```javascript
response.type()
```

--------------------------------

### Get response header

Source: https://japa.dev/docs/plugins/api-client

Returns the value for a specific response header.

```javascript
response.header('X-Time')
```

--------------------------------

### Configure snapshot plugin options

Source: https://japa.dev/docs/plugins/snapshot

Customize snapshot paths and formatting options in the configuration.

```javascript
configure({
  files: ['tests/**/*.spec.js'],
  plugins: [
    snapshot({
      resolveSnapshotPath: (testPath) => {
        /**
         * This will create a snapshot file next to your
         * test file.
         */
        return testPath.replace('.spec.ts', '.spec.ts.cjs')
      },
      prettyFormatOptions: {
        printFunctionName: true
      }
    })
  ]
})
```

--------------------------------

### Get all response cookies

Source: https://japa.dev/docs/plugins/api-client

Returns all cookies as an object of key-value pairs.

```javascript
response.cookies()
```

--------------------------------

### Run tests with c8

Source: https://japa.dev/docs/coverage

Execute the test script to generate coverage metrics.

```bash
npm test
```

--------------------------------

### Get response charset

Source: https://japa.dev/docs/plugins/api-client

Returns the response charset if specified in the content type.

```javascript
response.charset()
```

--------------------------------

### Run tests by filename pattern

Source: https://japa.dev/docs/filtering-tests

Run tests from any filename ending with 'register'.

```bash
node bin/test.js --files="register"
```

--------------------------------

### Get response error details

Source: https://japa.dev/docs/plugins/api-client

Returns the response error object and its properties.

```javascript
response.error()



// Response status

response.error().status



// Error text

response.error().text
```

--------------------------------

### View Japa CLI options with --help flag

Source: https://japa.dev/docs/installation

Displays the available options and flags for the Japa test runner.

```bash
node bin/test.js --help
```

--------------------------------

### Register API client plugin

Source: https://japa.dev/docs/plugins/api-client

Register the plugin within the entry point file, such as bin/test.js.

```javascript
import { apiClient } from '@japa/api-client'
import { configure } from '@japa/runner'

configure({
  files: ['tests/**/*.spec.js'],
  plugins: [apiClient('https://localhost:3333')]
})
```

--------------------------------

### client.options(endpoint)

Source: https://japa.dev/docs/plugins/api-client

Make an OPTIONS request to the specified endpoint. Returns a Response instance.

```APIDOC
## client.options(endpoint)

### Description
Performs an HTTP OPTIONS request to the given endpoint.

### Method
OPTIONS

### Endpoint
{baseUrl}{endpoint}

### Parameters
#### Path Parameters
- **endpoint** (string) - Required - The request endpoint path.

### Response
Returns a Response instance with methods: status(), body(), method(), headers().
```

--------------------------------

### fs.readDir

Source: https://japa.dev/docs/plugins/file-system

Get an array of files for a directory. The return value is an array of EntryInfo objects.

```APIDOC
## fs.readDir

### Description
Get an array of files for a directory. The return value is an array of EntryInfo objects.

### Method
fs.readDir

### Parameters
#### Arguments
- **filePath** (String) - Required - Path to the directory.

### Request Example
```js
test('copy files', async ({ fs }) => {
  const entries = await fs.readDir('make')
  entries.forEach((entry) => {
    console.log(entry.path)
    console.log(entry.fullPath)
    console.log(entry.basename)
    console.log(entry.stats)
  })
})
```

### Response
Returns an array of EntryInfo objects, each containing `path`, `fullPath`, `basename`, and `stats` properties.
```

--------------------------------

### Configure contextOptions

Source: https://japa.dev/docs/plugins/browser-client

Sets default options for browser contexts, such as baseURL and colorScheme.

```javascript
browserClient({
  contextOptions: {
    baseURL: 'http://localhost:3333',
    colorScheme: 'dark',
  }
})
```

--------------------------------

### response.redirects

Source: https://japa.dev/docs/plugins/api-client

Accesses the redirects the request followed before getting the response. Returns an array of URLs.

```APIDOC
## response.redirects

### Description
Accesses the redirects the request followed before getting the response.

### Method
response.redirects()

### Parameters
None.

### Request Example
```js
response.redirects()
```

### Response
Returns an array of URLs.
```

--------------------------------

### Run shards from the command line with --shard flag

Source: https://japa.dev/docs/filtering-tests

Use the --shard flag with the current/total format to run a specific shard. Each command runs a different shard; running all shards from 1 to total runs each test file exactly once.

```bash
node bin/test.js --shard=1/3

node bin/test.js --shard=2/3

node bin/test.js --shard=3/3
```

--------------------------------

### Get response files

Source: https://japa.dev/docs/plugins/api-client

Accesses files returned by the server when content type is multipart/form-data.

```javascript
response.files()
```

--------------------------------

### CLI flag --browser usage

Source: https://japa.dev/docs/plugins/browser-client

Use the --browser flag to specify the browser engine at runtime when no custom launcher is defined.

```bash
node bin/test.js --browser=chromium



node bin/test.js --browser=webkit



node bin/test.js --browser=firefox
```

--------------------------------

### Get response body

Source: https://japa.dev/docs/plugins/api-client

Returns the parsed response body for supported content types.

```javascript
response.body()
```

--------------------------------

### Configuring the API client plugin

Source: https://japa.dev/docs/plugins/api-client

Configure the plugin with the routes registry and an optional pattern serializer.

```typescript
import { apiClient } from '@japa/api-client'

export const plugins: Config['plugins'] = [
  apiClient({
    baseURL: 'http://localhost:3333',
    registry: routesRegistry,
    patternSerializer: (pattern, params) => {
      // Convert pattern like '/users/:id' to '/users/1'
      return pattern.replace(/:(\w+)/g, (_, key) => String(params[key] ?? ''))
    },
  }),
]
```

--------------------------------

### Run browser tests via CLI

Source: https://japa.dev/docs/plugins/browser-client

Commands to execute tests, including running specific suites, launching in headed mode, and enabling slow motion.

```bash
node bin/test.js

# Run tests for browser suite
node bin/test.js browser

# Launch browser
node bin/test.js browser --headed

# Run in slow motion
node bin/test.js browser --headed --slow
```

--------------------------------

### Failure tree group node structure

Source: https://japa.dev/docs/test-reporters

Example of a group node within the failure tree.

```json
{

  name: 'polls list',

  type: 'group',

  errors: [],

  children: [ [Object] ]

}
```

--------------------------------

### Run Japa tests with node bin/test.js

Source: https://japa.dev/docs/installation

Executes the Japa entry point file to run all tests. The entry point acts as a mini CLI application.

```bash
node bin/test.js
```

--------------------------------

### Configure test suites

Source: https://japa.dev/docs/installation

Defining test suites in the entry point file to organize tests by type and manage suite-specific lifecycle hooks.

```javascript
import { configure } from '@japa/runner'

configure({
  files: ['tests/**/*.spec.js'],
  suites: [
    {
      name: 'unit',
      files: 'tests/unit/**/*.spec.js'
    },
    {
      name: 'functional',
      files: 'tests/functional/**/*.spec.js',
      configure(suite) {
        /**
         * Example showcasing how to start the HTTP
         * server before running tests from the
         * functional suite.
         */
        suite.setup(() => {
          const server = startHttpServer()
          return () => server.close()
        })
      }
    }
  ],
  plugins: [
    assert(),
    expectTypeOf(),
  ],
})
```

--------------------------------

### Failure tree suite node structure

Source: https://japa.dev/docs/test-reporters

Example of a suite node within the failure tree.

```json
{

  name: 'functional',

  type: 'suite',

  errors: [],

  children: [Array]

}
```

--------------------------------

### with

Source: https://japa.dev/docs/reference/test

Defines the dataset for the test. The dataset must be an array, and the test will execute for each item in the array.

```APIDOC
## with

### Description
Define the dataset for the test. The dataset must be an array, and the test will execute for each item in the array.

### Method
with

### Usage
```
test('validate email')

  .with(['virk@adonisjs.com', 'foo@bar.com'])

  .run(async (ctx, email) => {

    // executed for each email    

  })
```

You can fetch the dataset lazily by defining a function.

```
async function getTestEmails () {

  return ['virk@adonisjs.com', 'foo@bar.com'] 

}



test('validate email')

  .with(getTestEmails)

  .run(async (ctx, email) => {

    // executed for each email    

  })
```

### See Also
Datasets
```

--------------------------------

### fs.mkdir

Source: https://japa.dev/docs/plugins/file-system

Creates a directory recursively inside the root of the file system.

```javascript
test('copy files', async ({ fs }) => {

  await fs.mkdir('make/controller')

})
```

--------------------------------

### toBeArray expects array type

Source: https://japa.dev/docs/plugins/expect-type

Expects the value to be of type array. The example passes an array of numbers.

```typescript
expectTypeOf([1, 2]).toBeArray()
```

--------------------------------

### toBeFunction expects function type

Source: https://japa.dev/docs/plugins/expect-type

Expects the value to be of type function. The example passes an arrow function.

```typescript
expectTypeOf(() => {}).toBeFunction()
```

--------------------------------

### Upload files using Buffer or Readable Stream

Source: https://japa.dev/docs/plugins/api-client

Demonstrates uploading file content using a readable stream or a Buffer.

```javascript
await client

  .post('/posts')

  .file('cover_image', createReadStream('./path/to/file'))



// Using buffer

await client

  .post('/posts')

  .file('cover_image', Buffer.from(binaryContents))
```

--------------------------------

### toBeAny expects any type

Source: https://japa.dev/docs/plugins/expect-type

Expects the value to be of type any. The example uses the data property from a got.post<any>() response.

```typescript
const { data } = await got.post<any>()

expectTypeOf(data).toBeAny()
```

--------------------------------

### Register fileSystem plugin in bin/test.js

Source: https://japa.dev/docs/plugins/file-system

Import and register the plugin within the Japa runner configuration.

```javascript
import { fileSystem } from '@japa/file-system'

import { configure } from '@japa/runner'



configure({

  files: ['tests/**/*.spec.js'],

  plugins: [fileSystem()]

})
```

--------------------------------

### Configure custom base directory and autoClean

Source: https://japa.dev/docs/plugins/file-system

Customize the base path for temporary files and toggle the automatic cleanup behavior in the plugin configuration.

```javascript
{

  plugins: [

    fileSystem({

      basePath: new URL('./tmp', import.meta.url),

      autoClean: false,

    })

  ]

}
```

--------------------------------

### Get response text

Source: https://japa.dev/docs/plugins/api-client

Returns the unparsed response body as text, available for specific content types.

```javascript
response.text()
```

--------------------------------

### qs(params)

Source: https://japa.dev/docs/plugins/api-client

Sets the query string for the request.

```APIDOC
## qs(params)

### Description
Sets the query string for the request.

### Method
qs

### Parameters
- **params** (object) - Required - An object of key-value pairs representing query parameters.

### Request Example
```js
request.qs({
  order_by: 'id',
  direction: 'desc'
})
```
```

--------------------------------

### Access context inside hooks

Source: https://japa.dev/docs/reference/test-context

Demonstrates accessing the test context within group setup and teardown hooks.

```typescript
import { test } from '@japa/runner'

test.group('Maths.add', (group) => {
  group.each.setup(($test) => {
    console.log($test.context)
  })

  group.each.teardown(($test) => {
    console.log($test.context)
  })

  test('add two number', (ctx) => {
    console.log(ctx)
  })
})
```

--------------------------------

### Define an HTTP server macro

Source: https://japa.dev/docs/test-macros

Creates a macro that initializes an HTTP server and registers a cleanup hook to close it when the test finishes.

```typescript
import { test } from '@japa/runner'
import { promisify } from 'node:utils'
import { createServer } from 'node:http'

export const useServer = test.macro((t, callback) => {
  /**
   * Create an HTTP server instance
   */
  const server = createServer(callback)

  /**
   * Assign the hook to close the server when test finishes
   */
  t.cleanup(() => promisify(server.close)())

  /**
   * Listen on some random port
   */
  server.listen(':0')

  /**
   * Return server instance
   */
  return server
})
```
Tokens:
Raw