Request Validator

Sometimes, for the same URL, we need to return different content based on different request parameters, but we don't want to handle it internally in the body function form. In this case, you can use the validator configuration to return different response content based on different request parameters.

Validate if GET request query matches

The link parameters only need to contain this parameter, no need for exact match.

import { defineMock } from 'vite-plugin-mock-dev-server'

export default defineMock([
  // match /api/post?id=1000
  {
    url: '/api/post',
    validator: {
      query: { id: '1000' },
    },
    body: {
      code: 200,
      message: 'success',
      result: {
        id: '1000',
        title: 'post-1000',
        content: 'post-1000 content',
        author: 'Mark',
      },
    },
  },
  {
    url: '/api/post',
    validator: {
      query: { id: '1001' },
    },
    body: {
      code: 200,
      message: 'success',
      result: {
        id: '1001',
        title: 'post-1001',
        content: 'post-1001 content',
        author: 'John',
      },
    },
  },
  {
    // match query include field `id` and value is 1003
    // like {url: '/api/post', validator: { query: { id: '1003' } }}
    url: '/api/post?id=1003',
    body: {
      code: 200,
      message: 'success',
      result: {
        id: '1003',
        title: 'post-1003',
        content: 'post-1003 content',
        author: 'Joy',
      },
    },
  },
  // Fallback, when the validator does not have a matching result, will use the configuration without validators as the response.
  {
    url: '/api/post',
    body: {
      code: 200,
      message: 'success',
      result: {
        id: 1000 + Math.floor(Math.random() * 1000),
        title: 'random post title',
      },
    },
  },
])

Validate if POST request body matches

The parameter needs to be included in the request body, exact match is not required.

import { defineMock } from 'vite-plugin-mock-dev-server'

export default defineMock([
  {
    url: '/api/post-update',
    validator: {
      body: {
        shouldUpdate: true,
      },
    },
    body: {
      code: 200,
      message: 'success',
      result: { updated: true },
    },
  },
  {
    url: '/api/post-update',
    validator: {
      body: {
        shouldUpdate: false,
      },
    },
    body: {
      code: 200,
      message: 'success',
      result: { updated: false },
    },
  },
])

Validate if params in dynamic path match

Validate if the params in the dynamic path match.

import { defineMock } from 'vite-plugin-mock-dev-server'

export default defineMock([
  // match /api/post/1001
  {
    url: '/api/post/:postId',
    validator: {
      params: { postId: '1001' },
    },
    body: {
      code: 200,
      message: 'success',
      result: {
        id: '1001',
        title: 'post-1001',
        content: 'post-1001 content',
      },
    },
  },
  // match /api/post/1002
  {
    url: '/api/post/:postId',
    validator: {
      params: { postId: '1002' },
    },
    body: {
      code: 200,
      message: 'success',
      result: {
        id: '1002',
        title: 'post-1002',
        content: 'post-1002 content',
      },
    },
  },
])

Validate if the request refererQuery parameters match

The source page address refers to the source address that initiates the mock API request. It can be a page opened in a browser that initiates a mock request, in which case the opened page is the source address. It can also be a mock API request initiated in a server request, in which case the server request is the source address.

The mock data content returned can be matched based on the query parameter in the source address.

import { defineMock } from 'vite-plugin-mock-dev-server'
import postList from './data/post'

// Different pages send the same interface and can get different
// data through the query parameter of the source page
export default defineMock([
  // localhost/post.html?from=post-page
  // send request /api/post/list
  {
    url: '/api/post/list',
    validator: {
      refererQuery: { from: 'post-page' },
    },
    body: {
      list: postList,
    },
  },
  // localhost/recommend.html?from=recommend-page
  // send request /api/post/list
  {
    url: '/api/post/list',
    validator: {
      refererQuery: { from: 'recommend-page' },
    },
    body: {
      list: postList.slice(0, 4),
    },
  },
])

Validator as a Function

Sometimes, strict parameter matching may not be sufficient for validation. In such cases, you can define a validator as a function and return a boolean value.

This allows you to perform more flexible validation on various information in the request.

import { defineMock } from 'vite-plugin-mock-dev-server'

export default defineMock([
  {
    url: '/api/validator-check-cookie',
    validator(request) {
      const token = request.getCookie('token')
      return !token
    },
    body: {
      message: 'token expired.',
    },
  },
  {
    url: '/api/validator-body-include',
    validator(request) {
      const ids = request.body.ids || []
      return !ids.includes('1001')
    },
    body: {
      code: 200,
      message: 'ids must be include 1001',
    },
  },
])

Deeply validate if the body matches

For the request body, which may have a relatively complex data structure, deep validation is required. The plugin supports checking if the body configured in the validator is a subset of the request body.

api.mock.ts

export default defineMock({
  url: '/mock/validator-body',
  validator: {
    body: {
      a: [1, 2], // The items in the array must all be in the 'a' of the request body
      b: { c: 1 }
    }
  },
  body: ''
})

fetch.ts

await fetch('/mock/validator-body', {
  method: 'POST',
  body: JSON.stringify({
    a: [1, 2, 3, 4],
    b: { c: 1, d: 2 },
    c: 1,
  })
})

INFO

Not only does the body in the validator support deep validation, but query, refererQuery, and others also support it.