🇺🇸English |
🇯🇵日本語
axios-mock-server
[![npm version][badge-npm]][badge-npm-url]
[![npm bundle size][badge-bundlephobia]][badge-bundlephobia-url]
[![CircleCI][badge-ci]][badge-ci-url]
[![Codecov][badge-coverage]][badge-coverage-url]
[![Language grade: JavaScript][badge-lgtm]][badge-lgtm-url]
[![Dependabot Status][badge-dependabot]][dependabot]
[![License][badge-license]][axios-mock-server-license]
RESTful mock server using axios.
Table of contents
- [Features](#features)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Tutorial](#tutorial)
- [Create API](#create-api)
- [Build API](#build-api)
- [Mocking Axios](#mocking-axios)
- [Examples](#examples)
- [Usage](#usage)
- [Create an API endpoint](#create-an-api-endpoint)
- [Connect to axios](#connect-to-axios)
- [Default](#default)
- [Each instance](#each-instance)
- [Functions](#functions)
- [`setDelayTime(millisecond: number): void`](#setdelaytimemillisecond-number-void)
- [`enableLog(): void` and `disableLog(): void`](#enablelog-void-and-disablelog-void)
- [TypeScript](#typescript)
- [Cautions](#cautions)
- [`.gitignore`](#gitignore)
- [`@ts-ignore`, `eslint-disable`](#ts-ignore-eslint-disable)
- [Troubleshooting](#troubleshooting)
- [`The expected type comes from property 'get' which is declared here on type 'MockMethods'` error in TypeScript](#the-expected-type-comes-from-property-get-which-is-declared-here-on-type-mockmethods-error-in-typescript)
- [Command Line Interface Options](#command-line-interface-options)
- [Configuration](#configuration)
- [License](#license)
## Features
- You can create a `GET`/`POST`/`PUT`/`DELETE` API endpoint in a few lines.
- A dedicated server is not required.
- It works with SPA as a static [JavaScript][javascript] file.
- You can use [axios][axios] as mock-up even in [Node.js][nodejs] environment.
- There is an auto-routing function similar to [Nuxt.js][nuxtjs], and no path description is required.
- Supports [TypeScript][typescript].
## Getting Started
### Installation
- Using [npm][npm]:
```sh
$ npm install axios
$ npm install axios-mock-server --save-dev
```
- Using [Yarn][yarn]:
```sh
$ yarn add axios
$ yarn add axios-mock-server --dev
```
### Tutorial
Introducing the simplest use of axios-mock-server.
Start the tutorial
#### Create API
First, create a `mocks` directory to store the files you want to mock up.
```sh
$ mkdir mocks
```
Next, create an API endpoint file in the `mocks` directory.
Let's define a mock API that retrieves basic user information with a `GET` request.
Create a `mocks/users` directory and create a `_userId.js` file.
```sh
$ mkdir mocks/users
$ touch mocks/users/_userId.js
# If Windows (Command Prompt)
> mkdir mocks\users
> echo. > mocks\users\_userId.js
```
Add the following to the `mocks/users/_userId.js` file.
```js
// file: 'mocks/users/_userId.js'
const users = [{ id: 0, name: 'foo' }, { id: 1, name: 'bar' }]
module.exports = {
get({ values }) {
return [200, users.find(user => user.id === values.userId)]
}
}
```
The routing of axios-mock-server is **automatically generated according to the tree structure of [JavaScript][javascript] and [TypeScript][typescript] files** in the `mocks` directory in the same way as the routing of [Nuxt.js][nuxtjs].
Reference: [Routing - Nuxt.js][nuxtjs-routing]
In other words, the `mocks/users/_userId.js` file **can define an endpoint using dynamic routing** as the path of `/users/:userId`.
#### Build API
axios-mock-server needs to build and generate the necessary files for routing before running.
```sh
$ node_modules/.bin/axios-mock-server
# If Windows (Command Prompt)
> node_modules\.bin\axios-mock-server
```
If the build is successful, the `$mock.js` file is generated in the`mocks` directory.
```sh
$ cat mocks/\$mock.js
/* eslint-disable */
module.exports = (client) => require('axios-mock-server')([
{
path: '/users/_userId',
methods: require('./users/_userId')
}
], client)
# If Windows (Command Prompt)
> type mocks\$mock.js
```
#### Mocking Axios
Finally, import the `mocks/$mock.js` file generated by `index.js` file etc. and pass it to the argument of axios-mock-server.
axios-mock-server will mock up all [axios][axios] communications by default.
```js
// file: 'index.js'
const axios = require('axios')
const mock = require('./mocks/$mock.js')
mock()
axios.get('https://example.com/users/1').then(({ data }) => {
console.log(data)
})
```
If you run the `index.js` file, you will see that `{ id: 1, name: 'bar' }` is returned.
```sh
$ node index.js
{ id: 1, name: 'bar' }
```
### Examples
axios-mock-server can be used to mock up **browser usage**, **data persistence** and **`multipart/form-data` format communication**.
It is also easy to link with [Nuxt.js][nuxtjs] ([@nuxtjs/axios][nuxtjs-axios]).
See [examples][axios-mock-server-examples] for source code.
See a list of use cases
- **[browser](https://github.com/solufa/axios-mock-server/tree/develop/examples/browser)**:
Use in browser
- **[node](https://github.com/solufa/axios-mock-server/tree/develop/examples/node)**:
Use in [Node.js][nodejs] (CommonJS)
- **[with-nuxtjs](https://github.com/solufa/axios-mock-server/tree/develop/examples/with-nuxtjs)**:
Using with a [Nuxt.js][nuxtjs]
- **[with-typescript](https://github.com/solufa/axios-mock-server/tree/develop/examples/with-typescript)**:
Using with a [TypeScript][typescript]
**WIP**
- with-in-memory-database
## Usage
### Create an API endpoint
```js
const users = [{ id: 0, name: 'foo' }, { id: 1, name: 'bar' }]
/**
* Type definitions for variables passed as arguments in requests
* @typedef { Object } MockMethodParams
* @property { import('axios').AxiosRequestConfig } config axios request settings
* @property {{ [key: string]: string | number }} values Dynamic value of the requested URL (underscore part of the path)
* @property {{ [key: string]: any }} params The value of the query parameter for the requested URL
* @property { any } data Request data sent by POST etc.
*/
/**
* Type definition when response is returned as an object
* @typedef { Object } MockResponseObject
* @property { number } status HTTP response status code
* @property { any? } data Response data
* @property {{ [key: string]: any }?} headers Response header
*/
/**
* Response type definition
* @typedef { [number, any?, { [key: string]: any }?] | MockResponseObject } MockResponse
*/
export default {
/**
* All methods such as GET and POST have the same type
* @param { MockMethodParams }
* @returns { MockResponse }
*/
get({ values }) {
return [200, users.find(user => user.id === values.userId)]
},
/**
* You can also return a response asynchronously
* @param { MockMethodParams }
* @returns { Promise }
*/
async post({ data }) {
await new Promise(resolve => setTimeout(resolve, 1000))
users.push({
id: users.length,
name: data.name
})
return { status: 201 }
}
}
```
### Connect to axios
#### Default
axios-mock-server will mock up all [axios][axios] communications by default.
```js
import axios from 'axios'
import mock from './mocks/$mock.js'
mock()
axios.get('https://example.com/api/foo').then(response => {
/* ... */
})
```
#### Each instance
You can also mock up each [axios instance][axios-instance].
```js
import axios from 'axios'
import mock from './mocks/$mock.js'
const client = axios.create({ baseURL: 'https://example.com/api' })
mock(client)
client.get('/foo').then(response => {
/* ... */
})
// axios will not be mocked up
axios.get('https://example.com/api/foo').catch(error => {
console.log(error.response.status) // 404
})
```
### Functions
axios-mock-server has several built-in functions available.
#### `setDelayTime(millisecond: number): void`
Simulate response delay.
```js
import axios from 'axios'
import mock from './mocks/$mock.js'
mock().setDelayTime(500)
console.time()
axios.get('https://example.com/api/foo').then(() => {
console.timeEnd() // default: 506.590ms
})
```
#### `enableLog(): void` and `disableLog(): void`
Switch request log output.
```js
import axios from 'axios'
import mock from './mocks/$mock.js'
const mockServer = mock()
;(async () => {
// To enable
mockServer.enableLog()
await axios.get('/foo', { baseURL: 'https://example.com/api', params: { bar: 'baz' } }) // stdout -> [mock] get: /foo?bar=baz => 200
// To disable
mockServer.disableLog()
await axios.get('/foo', { baseURL: 'https://example.com/api', params: { bar: 'baz' } }) // stdout ->
})()
```
### TypeScript
axios-mock-server includes [TypeScript][typescript] definitions.
### Cautions
#### `.gitignore`
Exclude `$mock.js` or `$mock.ts` generated by axios-mock-server in the build from [Git][git] monitoring.
```sh
$ echo "\$mock.*" >> .gitignore
# If Windows (Command Prompt)
> echo $mock.* >> .gitignore
```
#### `@ts-ignore`, `eslint-disable`
For [TypeScript][typescript] projects, add a `// @ ts-ignore` comment to the above line that imports`$ mock.ts`.
If [`@typescript-eslint/ban-ts-ignore`][typescript-eslint-ban-ts-ignore] rule is enabled in [typescript-eslint][typescript-eslint], please exclude the `// @ ts-ignore` comment from [ESLint][eslint].
```ts
// eslint-disable-next-line @typescript-eslint/ban-ts-ignore
// @ts-ignore: Cannot find module
import mock from './mocks/$mock'
```
## Troubleshooting
### `The expected type comes from property 'get' which is declared here on type 'MockMethods'` error in TypeScript
When returning a response asynchronously with [TypeScript][typescript], an error occurs because the type does not match if you try to make the response an array.
Assert `MockResponse` or return it as an object.
Example of error (**Note that the axios-mock-server build will pass!**)
```ts
import { MockMethods } from 'axios-mock-server'
const methods: MockMethods = {
async get() {
await new Promise(resolve => setTimeout(resolve, 100))
return [200, { foo: 'bar' }] // Error
}
}
export default methods
```
Resolve by asserting `MockResponse`.
```ts
import { MockMethods, MockResponse } from 'axios-mock-server'
const methods: MockMethods = {
async get() {
await new Promise(resolve => setTimeout(resolve, 100))
return [200, { foo: 'bar' }] as MockResponse // Type safe
}
}
export default methods
```
If the response can be an object, no assertion is required.
```ts
import { MockMethods } from 'axios-mock-server'
const methods: MockMethods = {
async get() {
await new Promise(resolve => setTimeout(resolve, 100))
return { status: 200, data: { foo: 'bar' } } // Type safe
}
}
export default methods
```
## Command Line Interface Options
The following options can be specified in the Command Line Interface.
| Option |
Type |
Default |
Description |
--config
-c |
string |
".mockserverrc" |
Specify the path to the configuration file. |
--watch
-w |
|
|
Enable watch mode.
Regenerate $mock.js or $mock.ts according to
the increase / decrease of the API endpoint file.
|
--version
-v |
|
|
Print axios-mock-server version. |
## Configuration
Settings are written in `.mockserverrc` file with JSON syntax.
| Option |
Type |
Default |
Description |
input |
string | string[] |
"mocks" or "apis" |
Specify the directory where the API endpoint file is stored.
If multiple directories are specified, $mock.js or
$mock.ts is generated in each directory.
|
outputExt |
"js" | "ts" |
|
Specify the extension of the file to be generated.
The default is set automatically from scripts of the API endpoint file.
|
outputFilename |
string |
"$mock.js" or "$mock.ts" |
Specify the filename to be generated. |
target |
"es6" | "cjs" |
|
Specify the code of the module to be generated.
The default is set automatically from extension of the API endpoint
file.
|
## License
axios-mock-server is licensed under a [MIT License][axios-mock-server-license].
[axios-mock-server-examples]: https://github.com/solufa/axios-mock-server/tree/develop/examples
[axios-mock-server-license]: https://github.com/solufa/axios-mock-server/blob/develop/LICENSE
[badge-bundlephobia-url]: https://bundlephobia.com/result?p=axios-mock-server@latest
[badge-bundlephobia]: https://img.shields.io/bundlephobia/min/axios-mock-server
[badge-ci-url]: https://circleci.com/gh/solufa/axios-mock-server
[badge-ci]: https://img.shields.io/circleci/build/github/solufa/axios-mock-server.svg?label=test
[badge-coverage-url]: https://codecov.io/gh/solufa/axios-mock-server
[badge-coverage]: https://img.shields.io/codecov/c/github/solufa/axios-mock-server.svg
[badge-dependabot]: https://api.dependabot.com/badges/status?host=github&repo=solufa/axios-mock-server
[badge-lgtm-url]: https://lgtm.com/projects/g/solufa/axios-mock-server/context:javascript
[badge-lgtm]: https://img.shields.io/lgtm/grade/javascript/g/solufa/axios-mock-server.svg
[badge-license]: https://img.shields.io/npm/l/axios-mock-server
[badge-npm-url]: https://www.npmjs.com/package/axios-mock-server
[badge-npm]: https://img.shields.io/npm/v/axios-mock-server
[axios-instance]: https://github.com/axios/axios#creating-an-instance
[axios]: https://github.com/axios/axios
[dependabot]: https://dependabot.com
[eslint]: https://eslint.org
[git]: https://git-scm.com/
[javascript]: https://developer.mozilla.org/en-US/docs/Web/JavaScript
[nodejs]: https://nodejs.org/
[npm]: https://www.npmjs.com/
[nuxtjs-axios]: https://github.com/nuxt-community/axios-module
[nuxtjs-routing]: https://nuxtjs.org/guide/routing
[nuxtjs]: https://nuxtjs.org/
[typescript-eslint-ban-ts-ignore]: https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/docs/rules/ban-ts-ignore.md
[typescript-eslint]: https://github.com/typescript-eslint/typescript-eslint
[typescript]: https://www.typescriptlang.org/
[yarn]: https://yarnpkg.com/