Japa

https://v2.japa.dev/docs
Admin
Japa is a simple yet powerful testing framework for Node.js that supports asynchronous tests, API...
Tokens:61,403
Snippets:612
Trust Score:7.5
Update:11 months ago
Show doc for...
Tokens:
Raw
### Create Test Directory and Sample Test File

Source: https://v2.japa.dev/docs/usage

Commands to create the `tests` directory and a sample test file named `maths.spec.js`. This is a common setup for organizing test files in Japa projects.

```bash
mkdir tests
touch tests/maths.spec.js
```

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

### Write a Sample Test using Japa (CommonJS)

Source: https://v2.japa.dev/docs/usage

Example of writing a test case using Japa's CommonJS syntax. It requires the `test` function from `@japa/runner` and defines a test for a simple sum function.

```javascript
const { test } = require('@japa/runner')

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

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

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

### Write a Sample Test using Japa (ESM)

Source: https://v2.japa.dev/docs/usage

Example of writing a test case using Japa's ESM syntax. It imports the `test` function from `@japa/runner` and defines a test for a simple sum function.

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

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

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

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

### Install Japa Test Runner using npm

Source: https://v2.japa.dev/docs/usage

Command to install the Japa test runner and initialize its configuration in a Node.js project. It uses `process.cwd()` to determine the project root for creating configuration and test files.

```bash
npm init japa@1.2.2
```

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

### Japa Plugin Defining Lifecycle Hooks (Setup Example)

Source: https://v2.japa.dev/docs/creating-plugins

This Japa plugin demonstrates how to define lifecycle hooks within suites and groups. It specifically shows how to set up a hook to launch and close a browser instance for each test.

```javascript
function myCustomPlugin() {

  return async function (config, runner, { Test, TestContext, Group }) {

    runner.onSuite((suite) => {

      // Here you have access to the suite



      suite.onGroup((group) => {

        // Here you have access to the group



        group.each.setup(async (test) => {

          test.context.browser = await chromium.launch()

          return async () => {

            await test.context.browser.close()

          }

        })

      })

    })

  }

}
```

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

### Run Japa Tests using Node.js

Source: https://v2.japa.dev/docs/usage

Command to execute Japa tests by directly running the `bin/test.js` file using Node.js. Japa does not provide a dedicated CLI; instead, it relies on this script for test execution and configuration.

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

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

### Install Japa Snapshot Plugin

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

Installs the Japa snapshot plugin and its peer dependencies (@japa/expect or @japa/assert) using npm.

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

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

### Install Japa Assert Plugin

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

Installs the Japa Assert plugin version 1.4.1 as a development dependency using npm.

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

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

### Define Global Setup Lifecycle Hook (CommonJS)

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

Configures a global setup hook that runs before each API request in a CommonJS module system. This allows for consistent setup actions across all requests.

```javascript
const { ApiClient } = require('@japa/api-client')

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

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

### ESM Test with Setup and Teardown Hooks

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

Demonstrates registering setup and teardown hooks for an individual test using ESM syntax. The setup hook runs before the test, and the teardown hook runs after the test. This is useful for setting up preconditions or cleaning up resources specific to a single test.

```javascript
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')
})
```

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

### CommonJS Test with Setup and Teardown Hooks

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

Illustrates registering setup and teardown hooks for an individual test using CommonJS syntax. The setup hook executes prior to the test, and the teardown hook executes after the test. This pattern is beneficial for managing test-specific prerequisites and post-test cleanup.

```javascript
const { test } = require('@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')
})
```

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

### Install Japa API Client Package

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

Install the @japa/api-client package from npm registry using npm or yarn package managers. This is the first step to set up the API client plugin for testing HTTP endpoints.

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

```bash
yarn add -D @japa/api-client@1.4.4
```

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

### Install Browser Client Dependencies

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

Installs the necessary Japa assertion plugin, Playwright, and the browser client plugin using npm. These are peer dependencies required for the browser client to function.

```bash
npm i -D @japa/assert@1.4.1 playwright
npm i -D @japa/browser-client@1.2.0
```

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

### Basic Browser Client Test Example

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

An example of a browser test using the Japa runner. It visits a URL, interacts with a link, and asserts the resulting page path and content. This demonstrates the basic usage of the `visit` helper and Playwright assertions.

```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')

})
```

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

### Install Base Reporter

Source: https://v2.japa.dev/docs/creating-reporters

Instructs on how to install the `@japa/base-reporter` package from the npm registry using npm. This package simplifies the creation of custom Japa reporters by providing a base class.

```bash
npm i @japa/base-reporter
```

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

### Install Japa Dot Reporter

Source: https://v2.japa.dev/docs/plugins/dot-reporter

Installs the @japa/dot-reporter package as a development dependency using npm. This is the first step to integrating the dot reporter into your Japa test suite.

```bash
npm i -D @japa/dot-reporter@1.1.1
```

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

### Define Setup Hook for Test in JavaScript

Source: https://v2.japa.dev/docs/underlying-test-class

Specifies a setup hook function that executes before the test runs. This is useful for preparing the test environment or data.

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

})

.setup(async () => {

  // executed before the test

})

```

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

### Teardown Hook Execution Problem with Failed Setup

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

Illustrates the limitation of teardown hooks when a setup hook fails. All teardown hooks execute regardless of which setup succeeded, potentially causing errors when trying to access undefined state. This example shows a browser variable remaining null when the first setup fails.

```javascript
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 @japa/run-failed-tests Plugin

Source: https://v2.japa.dev/docs/plugins/run-failed-tests

Installs the @japa/run-failed-tests plugin version 1.1.1 as a development dependency using npm.

```bash
npm i -D @japa/run-failed-tests@1.1.1
```

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

### Get Request Instance

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

Demonstrates how to obtain a request instance for different HTTP methods (GET, POST, PUT, PATCH, TRACE) using the client object.

```javascript
const request = client.get('/')

const request = client.post('/')

const request = client.put('/')

const request = client.patch('/')

const request = client.request('/', 'TRACE')
```

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

### Cleanup Function with Failed Setup Hook

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

Demonstrates the advantage of cleanup functions over teardown hooks. When the first setup hook fails, the second setup hook never executes, so no cleanup function is returned. This prevents attempts to close an undefined browser variable.

```javascript
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', () => {
  })
})
```

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

### Install Japa File System Plugin via npm

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

Install the @japa/file-system package as a development dependency. This package provides file system management capabilities for Japa test runner.

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

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

### Define Global Setup Lifecycle Hook (ESM)

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

Sets up a global setup hook that executes before every API request in an ESM environment. This hook can be used for tasks like preparing the environment or logging.

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

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

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

### ESM Group with Group Setup and Teardown Hooks

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

Demonstrates defining setup and teardown hooks at the group level using ESM syntax. The `group.setup` hook runs once before all tests in the group, and `group.teardown` runs once after all tests in the group, useful for initializing and finalizing shared resources.

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

test.group('Maths.add', (group) => {
  group.setup(() => {
    console.log('executed before all the test')
  })

  group.teardown(() => {
    console.log('executed after all the test')
  })
  
  test('add two numbers', () => {
    console.log('TEST 1 - executed in the test')
  })

  test('add two or more numbers', () => {
    console.log('TEST 2 - executed in the test')
  })
})
```

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

### Setup and Teardown Hooks for a Group

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

Registers `setup` and `teardown` hooks for a test group. The `setup` hook runs before all tests in the group, and the `teardown` hook runs after all tests have completed.

```javascript
test.group('Maths.add', (group) => {

  group.setup(() => {

    console.log('before all the tests')

  })


  group.teardown(() => {

    console.log('after all the tests')

  })


  test('add two numbers', ({ assert }) => {

    assert.equal(2 + 2, 4)

  })

})
```

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

### Extend BaseReporter with Lifecycle Handlers - TypeScript

Source: https://v2.japa.dev/docs/creating-reporters

Create a custom reporter by extending BaseReporter and implementing lifecycle methods that are invoked when test runner events occur. Handlers include onTestStart, onTestEnd, onGroupStart, onGroupEnd, onSuiteStart, onSuiteEnd, start, and end methods. The start and end methods support async operations for setup and teardown logic.

```typescript
import { BaseReporter } from '@japa/base-reporter'

class MyReporter extends BaseReporter {
  protected onTestStart(payload: TestStartNode) {
    console.log('test started')
  }

  protected onTestEnd(payload: TestEndNode) {
    console.log('test endeded')
  }

  protected onGroupStart(payload: GroupStartNode) {
    console.log('group started')
  }

  protected onGroupEnd(payload: GroupEndNode) {
    console.log('group ended')
  }

  protected onSuiteStart(payload: SuiteStartNode) {
    console.log('suite started')
  }

  protected onSuiteEnd(payload: SuiteEndNode) {
    console.log('suite ended')
  }

  protected async start(payload: RunnerStartNode) {
    console.log('test runner started. You can run async operations here')
  }

  protected async end(payload: RunnerEndNode) {
    console.log('test runner ended. You can run async operations here')
  }
}
```

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

### Install Japa Spec Reporter Package

Source: https://v2.japa.dev/docs/plugins/spec-reporter

Install the @japa/spec-reporter package from npm registry as a development dependency. This package provides the spec reporter functionality for displaying detailed test results in the terminal.

```bash
npm i -D @japa/spec-reporter@1.3.3
```

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

### Return Cleanup Function from Setup Hook in Japa

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

Demonstrates how to return a cleanup function from a setup hook to manage database table lifecycle. The cleanup function is automatically called after the test to drop tables created during setup. This pattern ensures cleanup only runs if setup succeeds, unlike teardown hooks which always run.

```ESM
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', () => {
  })
})
```

```CommonJS
const { test } = require('@japa/runner')

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

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

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

### Define Request-Specific Lifecycle Hooks

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

Applies setup and teardown hooks to an individual request. The setup hook returns a teardown function, allowing for localized resource management for a single request cycle.

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

  response.assertStatus(200)
})
```

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

### Install c8 Code Coverage Tool

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

Install the c8 package as a development dependency from npm registry. c8 is a modern code coverage tool that works with Node.js for collecting coverage metrics.

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

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

### Install @japa/expect Plugin via npm

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

Install the @japa/expect plugin version 2.0.2 as a development dependency. This plugin provides Jest-compatible assertion methods for use in Japa test files.

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

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

### ESM Group with Each Setup and Teardown Hooks

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

Shows how to apply setup and teardown hooks to all tests within a group using `group.each.setup` and `group.each.teardown` in ESM. These hooks run before and after each individual test inside the group, respectively, reducing repetitive hook definitions.

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

test.group('Maths.add', (group) => {
  group.each.setup(() => {
    console.log('executed before the test')
  })

  group.each.teardown(() => {
    console.log('executed after the test')
  })

  test('add two numbers', () => {
    console.log('TEST 1 - executed in the test')
  })

  test('add two or more numbers', () => {
    console.log('TEST 2 - executed in the test')
  })
})
```

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

### Implement Reporter Event Listeners

Source: https://v2.japa.dev/docs/creating-reporters

Provides a detailed implementation of a custom Japa reporter that logs various test lifecycle events to the console. It uses `emitter.on()` to capture events like `runner:start`, `runner:end`, `suite:start`, `suite:end`, `group:start`, `group:end`, and `test:end`, adjusting indentation for nested structures.

```javascript
function logReporter() {

  return function (runner, emitter) {

    let indentation = 2

    function getSpaces() {

      return new Array(indentation + 1).join(' ')

    }



    emitter.on('runner:start', () => {

      console.log(`START`)

    })



    emitter.on('runner:end', () => {

      console.log(`FINISH: completed in "${runner.getSummary().duration}ms"`)

    })



    emitter.on('suite:start', (payload) => {

      console.log(`${getSpaces()}SUITE: "${payload.name}"`)

      indentation += 2

    })



    emitter.on('suite:end', (payload) => {

      indentation -= 2

      console.log(`${getSpaces()}SUITE: "${payload.name}" `)

    })



    emitter.on('group:start', (payload) => {

      console.log(`${getSpaces()}GROUP: "${payload.title}" `)

      indentation += 2

    })



    emitter.on('group:end', (payload) => {

      indentation -= 2

      console.log(`${getSpaces()}GROUP: "${payload.title}" `)

    })



    emitter.on('test:end', (payload) => {

      console.log(`${getSpaces()}TEST: "${payload.title}" completed in "${payload.duration}ms"`)

    })

  }

}
```

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

### Install @japa/expect-type Plugin

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

Install the @japa/expect-type package as a development dependency using npm. This package is required for enabling TypeScript type assertions within your Japa tests.

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

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

### Install Concurrently for Parallel Testing

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

Installs the 'concurrently' package as a development dependency, which is used to run multiple npm scripts in parallel. This is a prerequisite for running Japa test suites in parallel.

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

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

### Install ts-node for TypeScript Projects

Source: https://v2.japa.dev/docs/usage-with-typescript

Installs the 'ts-node' package as a development dependency, which is essential for running TypeScript files directly with Node.js.

```bash
npm i -D ts-node
```

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

### Request Initialization

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

Get an instance of the request class by calling HTTP request methods on the client object.

```APIDOC
## Request Initialization

### Description
Initialize a request instance using various HTTP methods or a generic request method.

### Methods
- `client.get(path)`
- `client.post(path)`
- `client.put(path)`
- `client.patch(path)`
- `client.request(path, method)`

### Example
```javascript
const request = client.get('/');
const request = client.post('/');
const request = client.put('/');
const request = client.patch('/');
const request = client.request('/', 'TRACE');
```
```

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

### Test Hook Parameters in Japa

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

Shows how setup and teardown hooks receive the Test class instance as their only argument. Allows access to test metadata and properties within lifecycle hooks.

```javascript
test.group((group) => {
  group.each.setup((test) => {
  })

  group.each.teardown((test) => {
  })
})
```

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

### False-Positive Test Example without Assertion Planning

Source: https://v2.japa.dev/docs/assertion-planning

This code demonstrates a test case that might result in a false-positive. If the `someOperation()` does not throw an error, the `catch` block is never executed, and thus the assertion is never made, potentially leading to a false-positive test result. This example is written in JavaScript.

```javascript
test('a false-positive test', async ({ assert }) => {

  try {

    await someOperation()

  } catch (error) {

    assert.equal(error.message, 'The expected error message')

  }

})
```

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

### Configure Suite Lifecycle Hooks

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

Configures a 'functional' test suite with a lifecycle hook that sets up an HTTP server before tests run and tears it down afterward. This allows for integration testing setup.

```javascript
configure({

  suites: [

    {

      name: 'functional',

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

      configure(suite) {

        suite.setup(() => {

          server = createServer(handler)

          server.start()



          return () => server.close()

        })

      },

    }

  ]

})
```

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

### Run Browser Client Tests

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

Demonstrates commands to run Japa tests. It shows how to run all tests, specifically browser tests, launch tests with the browser UI visible, and run tests in slow motion.

```bash
# Run all tests
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
```

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

### Assertion Planning with @japa/assert

Source: https://v2.japa.dev/docs/assertion-planning

This example shows how to implement assertion planning using the `@japa/assert` plugin. The `assert.plan(1)` method explicitly states that exactly one assertion is expected. If `someOperation()` does not throw an error, the test will fail because the planned assertion within the `catch` block will not be executed. This is written in JavaScript.

```javascript
test('a false-positive test', async ({ assert }) => {

  assert.plan(1)



  try {

    await someOperation()

  } catch (error) {

    assert.equal(error.message, 'The expected error message')

  }

})
```

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

### Custom Japa Plugin to Mutate Config

Source: https://v2.japa.dev/docs/creating-plugins

Example of a Japa plugin that modifies the test runner's configuration, specifically the 'files' property, by fetching a list of files.

```javascript
function myCustomPlugin() {

  return async function (config, runner, { Test, TestContext, Group }) {

    config.files = await getListOfFiles()

  }

}
```

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

### Configure Suite Groups and Tests

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

Demonstrates how to configure individual tests and groups within a Japa test suite using `onTest` and `onGroup` methods. This allows fine-grained control over test setups.

```javascript
configure(suite) {

  suite.onTest((test) => {

    test.setup(() => {}) // Setup for individual tests

  })



  suite.onGroup((group) => {

    group.tap((test) => {

      test.setup(() => {}) // Setup for tests within a group

    })

  })

}
```

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

### Group Hook Parameters in Japa

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

Shows how group-level setup and teardown hooks receive the Group class instance. The instance reference is identical to the group parameter passed to the callback.

```javascript
test.group((group) => {
  group.setup((self) => {
    console.log(self === group)
  })

  group.teardown((self) => {
    console.log(self === group)
  })
})
```

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

### Get Response Status Type

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

Returns the general category of the response status code. For example, 301 redirects to type 3, and 404 errors to type 4.

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

response.status() // 404
response.statusType() // 4

response.status() // 202
response.statusType() // 2
```

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

### Run Failed Tests with @japa/run-failed-tests Plugin (CommonJS)

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

Install and configure the `@japa/run-failed-tests` plugin for subsequent test runs. This plugin automatically reruns only the tests that failed in the previous execution. If all tests passed, it runs all tests. This example demonstrates its usage with CommonJS.

```javascript
npm i @japa/run-failed-tests
```

```javascript
const { runFailedTests } = require('@japa/run-failed-tests')

configure({
  plugins: [runFailedTests()]
})
```

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

### Browser Client Plugin Configuration Options

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

Shows the configuration options available when registering the browser client plugin. This includes setting `runInSuites`, `contextOptions`, and detailed `tracing` configurations for managing browser test execution.

```javascript
plugins: [

  browserClient({

    runInSuites: ['browser'],

    contextOptions: {},

    tracing: {

      enabled: false,

      event: 'onError',

      cleanOutputDirectory: true,

      outputDirectory: join(__dirname, '..')

    }

  })

]
```

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

### Run Failed Tests with @japa/run-failed-tests Plugin (ESM)

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

Install and configure the `@japa/run-failed-tests` plugin for subsequent test runs. This plugin automatically reruns only the tests that failed in the previous execution. If all tests passed, it runs all tests. This example demonstrates its usage with ESM.

```javascript
npm i @japa/run-failed-tests
```

```javascript
import { runFailedTests } from '@japa/run-failed-tests'

configure({
  plugins: [runFailedTests()]
})
```

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

### Make HTTP Requests with Different Methods

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

Execute HTTP requests using standard HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) by calling the corresponding methods on the client object. Each method accepts the request endpoint as the only argument.

```javascript
test('dummy test', async ({ client }) => {
  await client.get('/users')

  await client.post('/users')

  await client.put('/users')

  await client.patch('/users')

  await client.delete('/users')

  await client.head('/users')

  await client.options('/users')
})
```

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

### Run All Tests in Parallel

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

Executes the 'test' script defined in `package.json`, which uses 'concurrently' to run the unit and functional test suites simultaneously. This command leverages the parallel execution setup.

```bash
npm test
```

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

### Promisify event listeners using p-event

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

This example demonstrates how to promisify event listeners with the 'p-event' package. It allows tests to wait for specific events (like 'connected') or reject on error events, integrating seamlessly with async/await.

```javascript
import pEvent from 'p-event'

test('make redis connection', async (ctx) => {

  const redis = new Redis()

  

  await Promise.all([

    pEvent(

      redis,

      'connected',

      { rejectionEvents: ['error'] }

    ),



    redis.connect()

  ])

})
```

```javascript
const pEvent = require('p-event')


test('make redis connection', async (ctx) => {

  const redis = new Redis()

  

  await Promise.all([

    pEvent(

      redis,

      'connected',

      { rejectionEvents: ['error'] }

    ),



    redis.connect()

  ])

})
```

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

### Configure Dot Reporter (CommonJS)

Source: https://v2.japa.dev/docs/plugins/dot-reporter

Registers the dot reporter within the Japa runner configuration file (bin/test.js) using CommonJS syntax. This setup ensures that tests will be reported using the minimalist dot reporter.

```javascript
const { dotReporter } = require('@japa/dot-reporter')

const { configure, processCliArgs } = require('@japa/runner')



configure({

  ...processCliArgs(process.argv.slice(2)),

  ...{

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

    reporters: [dotReporter()]

  }

})
```

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

### Switch Browsers at Runtime via CLI

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

Allows switching between different browsers (Chromium, WebKit, Firefox) at runtime using the `--browser` CLI flag. This flag is used when a custom `launcher` method is not defined in the configuration.

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

node bin/test.js --browser=webkit

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

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

### Register Custom Decorators for Page, Context, and Response Objects

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

Extend Japa browser client objects using decoratorsCollection.register() to add custom methods to page, context, and response objects. This example adds getWidth() to page, injectShaHash() to context, and getResponseTime() to response, enabling encapsulation of reusable functionality.

```typescript
import { decoratorsCollection } from '@japa/browser-client'

decoratorCollection.register({
  page(page) {
    page.getWidth = function () {
      return this.viewportSize().width
    }
  },
  context(context) {
    context.injectShaHash = function () {
      this.exposeFunction('sha256', (text) => {
        return crypto.createHash('sha256').update(text).digest('hex')
      })
    }
  },
  response(response) {
    response.getResponseTime = function () {
      return this.headers()['x-response-time']
    }
  }
})
```

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

### Handle Async Operations in Reporters (ESM)

Source: https://v2.japa.dev/docs/creating-reporters

Demonstrates how to handle asynchronous operations, such as file I/O, within Japa reporters using ECMAScript Modules (ESM). It shows using `lockfile` for file locking and `fs.write` for writing to a file, ensuring these operations are managed within `runner:start` and `runner:end` events.

```javascript
import lockfile from 'proper-lockfile'



let release


emitter.on('runner:start', async () => {

  release = await lockfile('somefile.json')

})



emitter.on('runner:end', async () => {

  await fs.write('somefile.json', contents)

  await release()

})
```

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

### Run Selected Test Suites

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

Demonstrates how to execute specific test suites using the Japa test runner from the command line. You can specify one or multiple suite names to run.

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

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

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

### File Uploads

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

Demonstrates how to upload files using the `file` method, supporting file paths, buffers, and readable streams. Also shows how to submit form data alongside files using `fields`.

```APIDOC
## File Uploads

You can upload files using the `file` method. The method accepts the field name and path to the file as its value.
This method makes a `multipart/form-data` request to the server.

### Example with File Path
```javascript
await client.post('/posts').file('cover_image', join(__dirname, '..', 'cover-image.jpg'))
```

### Example with Readable Stream
```javascript
await client.post('/posts').file('cover_image', createReadStream('./path/to/file'))
```

### Example with Buffer
```javascript
await client.post('/posts').file('cover_image', Buffer.from(binaryContents))
```

When making a multipart request, you cannot use `form` or `json` methods. Instead, you must use either the `field` or `fields` methods to submit the form data.

### Example with Form Data
```javascript
await client.post('/posts')
  .file('cover_image', join(__dirname, '..', 'cover-image.jpg'))
  .fields({
    title: 'Japa 101',
    description: 'Something about the post',
    tags: [1, 2, 4]
  })
```
```

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

### Configure Japa with Assert Plugin (CommonJS)

Source: https://v2.japa.dev/docs/creating-plugins

This snippet demonstrates configuring the Japa test runner using CommonJS modules and integrating the assertion plugin.

```javascript
const { assert } = require('@japa/assert')
const { configure } = require('@japa/runner')



configure({

  plugins: [

    assert()

  ]

})
```

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

### Configure Browser Context Options

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

Sets configuration options for creating new browser contexts. These options are passed directly to the `browser.newContext` method, allowing customization of base URL, color scheme, and other context-specific settings.

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

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

### Setting Headers

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

Methods for setting request headers.

```APIDOC
## Setting Headers

### Description
Set individual or multiple headers for the request.

### Methods
#### `header(name, value)`
Sets a single header.

- **name** (string) - The name of the header.
- **value** (string | string[]) - The value of the header.

#### `headers(keyValuePair)`
Sets multiple headers from a key-value pair object.

- **keyValuePair** (object) - An object where keys are header names and values are header values.

### Examples
```javascript
// Set a single header
request.header('X-Request-Id', 'value');

// Set multiple headers
request.headers({
  'X-Request-Id': 'value',
  'X-Another-Header': 'another-value'
});
```
```

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

### Configure Browser and Unit Test Suites

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

Configures distinct test suites for browser and unit tests. It specifies file paths for each suite and ensures the browser client plugin only creates new browser contexts for tests within the 'browser' suite.

```javascript
configure({

  ...processCliArgs(process.argv.slice(2)),

  ...{

    suites: [

      {

        name: 'browser',

        timeout: 30 * 1000,

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

      },

      {

        name: 'unit',

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

      }

    ],

    plugins: [

      assert(),

      browserClient({

        runInSuites: ['browser']

      })

    ]

  }

})
```

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

### Create Reporter using Base Reporter (ESM)

Source: https://v2.japa.dev/docs/creating-reporters

Shows how to create a custom reporter using the `@japa/base-reporter` package with ECMAScript Modules (ESM). It involves extending the `BaseReporter` class and exporting a factory function `reporterFn` that instantiates and returns the reporter's boot method.

```javascript
import { BaseReporter } from '@japa/base-reporter'



class MyReporter extends BaseReporter {}



export const reporterFn = (myReporterOptions = {}) => {

  const myReporter = new MyReporter(myReporterOptions)

  return myReporter.boot.bind(reporter)

}
```

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

### Configure Multiple Browser Test Scripts in package.json

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

Define npm scripts for running tests on different browsers and sequentially executing tests across all browsers. Simplifies running comprehensive cross-browser test suites with single commands.

```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"
}
```

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

### Configure Japa with Assert Plugin (ESM)

Source: https://v2.japa.dev/docs/creating-plugins

This snippet shows how to configure the Japa test runner using ECMAScript Modules (ESM) and include the assertion plugin.

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

import { configure } from '@japa/runner'



configure({

  plugins: [

    assert()

  ]

})
```

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

### Configure Snapshot Plugin Options

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

Demonstrates configuring the Japa snapshot plugin with custom options, specifically `resolveSnapshotPath` to change the snapshot file location and `prettyFormatOptions` to customize output formatting.

```javascript
configure({

  ...processCliArgs(process.argv.slice(2)),

  ...{

    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

        }

      })

    ]

  }

})
```

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

### Basic Snapshot Assertion (Assert & Expect)

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

Demonstrates how to perform basic snapshot assertions using both `@japa/assert`'s `snapshot().match()` and `@japa/expect`'s `toMatchSnapshot()`. This creates or compares against a snapshot file.

```javascript
test('match snapshot', async ({ assert, expect }) => {

  // with @japa/assert

  assert.snapshot('1').match()



  // with @japa/expect

  expect('1').toMatchSnapshot()

})
```

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

### Japa Plugin Extending Classes with Macros and Getters

Source: https://v2.japa.dev/docs/creating-plugins

This plugin demonstrates extending Japa's core classes. It adds a 'visit' macro to the Test class, a lazy 'assert' getter to the TestContext, and a 'tags' macro to the Group class.

```javascript
function myCustomPlugin() {

  return async function (config, runner, { Test, TestContext, Group }) {

    Test.macro('visit', function () {

    })



    TestContext.getter('assert', function () {

    }, true)



    Group.macro('tags', function (tags) {

      this.each.tags(tags)

    })

  }

}
```

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

### Define and Configure a Custom Japa Plugin

Source: https://v2.japa.dev/docs/creating-plugins

This code illustrates how to define a custom plugin function and then configure the Japa test runner to use it.

```javascript
function myCustomPlugin() {

  return async function (config, runner, { Test, TestContext, Group }) {

  }

}





configure({

  plugins: [

    myCustomPlugin()

  ]

})
```

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

### Get Response Content-Type

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

Returns the content-type of the response.

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

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

### Get Response Status Code

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

Returns the HTTP status code of the response.

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

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

### Authentication

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

Methods for setting authentication credentials.

```APIDOC
## Authentication

### Description
Set authentication headers for the request.

### Methods
#### `basicAuth(username, password)`
Sets the `Authorization` header for Basic Authentication.

- **username** (string) - The username.
- **password** (string) - The password.

#### `bearerToken(token)`
Sets the `Authorization` header with a Bearer token.

- **token** (string) - The Bearer token.

### Examples
```javascript
// Set Basic Auth
request.basicAuth('virk', 'secret');
// Resulting header: Authorization: Basic dmlyazpzZWNyZXQ=

// Set Bearer Token
request.bearerToken('foo-bar');
// Resulting header: Authorization: Bearer foo-bar
```
```

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

### Get All Cookies

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

Returns all cookies present in the response as a key-value pair object.

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

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

### Get Specific Response Header Value

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

Retrieves the value of a specific response header by its name.

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

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

### Get Redirect History

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

Accesses the array of URLs that the request followed through redirects before reaching the final response.

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

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

### Get Response Files

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

Accesses files returned by the server. This method is only effective when the response content type is 'multipart/form-data'.

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

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

### Get All Response Headers

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

Returns all response headers as an object, where keys are header names and values are their corresponding values.

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

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

### Handling Redirects

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

Methods for configuring and inspecting request redirects.

```APIDOC
## Handling Redirects

### Description
Configure the request to follow server redirects and retrieve redirect links from the response.

### Methods
#### `redirects(count)`
Instructs the request to follow a specific number of server redirects.

- **count** (number) - The maximum number of redirects to follow. Defaults to 5.

### Examples
```javascript
// Follow 2 redirects from the server
request.redirects(2);

// Get redirect links from the response
const response = await request.redirects(2);
console.log(response.redirects());
```
```

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

### Get Parsed Response Body

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

Returns the parsed response body. Parsing occurs when the content-type is 'application/json', 'application/x-www-form-urlencoded', or 'multipart/form-data'.

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

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

### Get Response Charset

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

Returns the character set of the response. This property is only available if the response content type explicitly mentions the charset.

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

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

### Setting Content Type and Accept Header

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

Methods for setting the request's Content-Type and Accept headers.

```APIDOC
## Setting Content Type and Accept Header

### Description
Set the `Content-Type` and `Accept` headers for the request.

### Methods
#### `type(type)`
Sets the `Content-Type` header. Accepts a full MIME type or a shorthand.

- **type** (string) - The content type (e.g., 'json', 'application/xml').

#### `accept(type)`
Sets the `Accept` header. Accepts a full MIME type or a shorthand.

- **type** (string) - The accepted content type (e.g., 'json', 'application/xml').

### Examples
```javascript
// Set Content-Type to JSON
request.type('json'); // Content-type: application/json

// Set Accept header to JSON
request.accept('json'); // Accept: application/json
```
```

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

### Configure Reporters (CommonJS)

Source: https://v2.japa.dev/docs/creating-reporters

Demonstrates how to configure Japa reporters using CommonJS modules. It includes requiring the `specReporter` and `configure` function, and then defining the `reporters` array within the configuration object, including the standard spec reporter and a placeholder for a custom reporter.

```javascript
const { specReporter } = require('@japa/spec-reporter')

const { configure } = require('@japa/runner')



configure({

  reporters: [

    specReporter(),

    myCustomReporter()

  ]

})
```

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

### toBeUndefined Assertion Example

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

Asserts that a value is undefined using the toBeUndefined assertion. This helps in debugging and ensuring variables have been assigned a value.

```javascript
expectTypeOf(undefined).toBeUndefined()
```

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

### toBeString Assertion Example

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

Checks if a value is a string using the toBeString assertion. This is a common assertion for validating string inputs or outputs.

```javascript
expectTypeOf('hello world').toBeString()
```

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

### TLS Options

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

Methods for configuring TLS settings.

```APIDOC
## TLS Options

### Description
Configure TLS/SSL settings for the request. These methods work similarly to SuperAgent's TLS options.

### Methods
- **`ca(certificate)`**: Set the CA certificate(s) to trust.
- **`cert(certificate)`**: Set the client certificate chain(s).
- **`privateKey(key)`**: Set the client private key(s).
- **`pfx(pfx)`**: Set the client PFX or PKCS12 encoded private key and certificate chain.
- **`disableTLSCerts()`**: Accept expired or invalid TLS certificates. **Warning**: This allows Man-in-the-Middle (MITM) attacks. Internally sets `rejectUnauthorized=true` when used.

### Examples
```javascript
// Trust specific CA certificates
request.ca('-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----');

// Disable TLS certificate validation (use with caution)
request.disableTLSCerts();

// Disable TLS certificate validation explicitly
request.trustLocalhost(false);
```
```

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

### Automatically Open Browser DevTools via CLI

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

Opens the browser's developer tools automatically after launching the browser using the `--devtools` CLI flag. This also disables headless mode.

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

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

### toBeNullable Assertion Example

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

Checks if a value is null using the toBeNullable assertion. This is important for handling optional values or explicitly cleared states.

```javascript
expectTypeOf(null).toBeNullable()
```

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

### toBeSymbol Assertion Example

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

Checks if a value is a symbol using the toBeSymbol assertion. This is relevant when working with unique identifiers or object property keys.

```javascript
expectTypeOf(Symbol('foo')).toBeSymbol()
expectTypeOf(Symbol.for('foo')).toBeSymbol()
```

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

### Manually Launch Playwright Browser with Custom Options

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

Provides an optional function to manually launch a Playwright browser. Allows customization of launch options, overriding the default Chromium browser. Useful for specific browser configurations or integrations.

```javascript
import { firefox } from 'playwright'

browserClient({
  async launcher(options) {
    return firefox.launch({
      ...options,
      ...customOptionsToMerge
    })
  }
})
```

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

### toBeBoolean Assertion Example

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

Asserts that a value is a boolean (true or false) using the toBeBoolean assertion. This is crucial for conditional logic and flag management.

```javascript
expectTypeOf(true).toBeBoolean()
expectTypeOf(false).toBeBoolean()
```

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

### toBeArray Assertion Example

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

Asserts that a value is an array using the toBeArray assertion. This is useful for validating that a variable contains an array data structure.

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

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

### Use Page Object in Japa Tests

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

Demonstrates how to import and use the `PostsListingPage` page object within Japa tests. It shows how to visit the page and utilize its methods for expressive assertions, such as checking for an empty list, verifying the number of posts, and navigating through pagination.

```javascript
import { test } from '@japa/runner'
import { PostsListingPage } from './pages/listing_page.js'

test.group('Posts | list', () => {
  test('see an empty list, when posts does not exists', async ({ visit }) => {
    const page = await visit(PostsListingPage)
    await page.assertHasEmptyList()
  })

  test('see first 10 posts', async ({ visit }) => {
    await PostsFactory.createMany(10)
    const page = await visit(PostsListingPage)
    await page.assertPostsCount(10)
  })

  test('navigate using pagination', async ({ visit }) => {
    const posts = await PostsFactory.createMany(20)

    const page = await visit(PostsListingPage)
    await page.paginateTo(2)
    await page.assertHasPost(posts[10].title)
  })
})
```

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

### toBeObject Assertion Examples

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

Demonstrates the toBeObject assertion, which verifies if a value is an object. It accepts objects with any key-value pairs, including instances of classes.

```javascript
class Foo {}
expectTypeOf(new Foo()).toBeObject()
```

```javascript
const foo = {}
expectTypeOf(foo).toBeObject()
```

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

### toBeFunction Assertion Example

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

Checks if a value is a function using the toBeFunction assertion. This is a straightforward way to ensure that a variable holds a callable function.

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

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

### Overriding Plugin Timeout with Test-Specific Timeout

Source: https://v2.japa.dev/docs/creating-plugins

This example illustrates how a test's specific timeout setting can override a timeout configured by a plugin at the group level.

```javascript
runner.onSuite((suite) => {

  suite.onGroup((group) => {

    group.each.timeout(6000)

  })

})





test('visit google.com', () => {

}).timeout(2000) // 👈 Wins over plugin
```

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

### Get Response Error Object

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

Retrieves the error object from the response, if one exists. This object may contain properties like status and text.

```javascript
response.error()

// Response status
response.error().status

// Error text
response.error().text
```

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

### Setting Query String

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

Method for setting the query string parameters.

```APIDOC
## Setting Query String

### Description
Set the query string parameters for the request URL.

### Method
#### `qs(params)`
Sets the query string parameters.

- **params** (object) - An object where keys are parameter names and values are parameter values.

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

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

### Get Response Body as Text

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

Retrieves the unparsed response body as text. This method is available when the response content-type matches 'text/', '/json', or 'x-www-form-urlencoded'.

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

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

### Get File Stats

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

Retrieves the `fs.Stats` object for a file at the specified location. This object contains metadata about the file, such as its size, modification time, and type.

```typescript
test('read rc file', async ({ fs }) => {
  const stats = await fs.stats('rc.json')
})
```
Tokens:
Raw