Quick Start

Quick Start

Get up and running with MockMaster in 5 minutes.

Step 1: Create an OpenAPI Spec

Define your API using an OpenAPI 3.0 specification:

import { parseYaml } from '@mockmaster/openapi'
 
const spec = parseYaml(`
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id: { type: integer }
                    name: { type: string }
                    email: { type: string, format: email }
`)

You can also use JSON format:

import { parseSpec } from '@mockmaster/openapi'
 
const spec = parseSpec({
  openapi: '3.0.0',
  info: { title: 'User API', version: '1.0.0' },
  paths: {
    '/users': {
      get: {
        responses: {
          '200': {
            content: {
              'application/json': {
                schema: {
                  type: 'array',
                  items: {
                    type: 'object',
                    properties: {
                      id: { type: 'integer' },
                      name: { type: 'string' },
                      email: { type: 'string', format: 'email' }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
})

Step 2: Generate Scenarios

MockMaster automatically generates realistic data based on your schema types:

import { generateScenariosFromSpec } from '@mockmaster/cli'
 
const scenarios = generateScenariosFromSpec(spec, 'user-api')
// MockMaster generates realistic data based on your schema!

The generated scenarios will include:

  • Realistic names, emails, and data based on your schema types
  • Proper data types (integers, strings, booleans, etc.)
  • Format-aware generation (email, date, uri, etc.)

Step 3: Save Scenarios (Optional)

Save your scenarios to disk for version control:

import { writeScenario } from '@mockmaster/cli'
 
await writeScenario('./scenarios', scenarios[0])
// Saved to: ./scenarios/user-api.json

This creates a JSON file that you can commit with your code:

{
  "name": "user-api",
  "description": "Generated from OpenAPI spec",
  "recordings": [
    {
      "request": {
        "method": "GET",
        "path": "/users",
        "timestamp": 1234567890
      },
      "response": {
        "status": 200,
        "body": [
          { "id": 1, "name": "John Doe", "email": "john@example.com" },
          { "id": 2, "name": "Jane Smith", "email": "jane@example.com" }
        ],
        "timestamp": 1234567890
      }
    }
  ],
  "createdAt": 1234567890,
  "updatedAt": 1234567890
}

Step 4: Replay in Tests

Use the scenarios in your tests for deterministic API responses:

import { createReplayHandler } from '@mockmaster/msw-adapter'
 
const handler = createReplayHandler(scenarios[0])
const response = handler({ method: 'GET', path: '/users' })
 
console.log(response.status) // 200
console.log(response.body)
// [
//   { id: 1, name: 'John Doe', email: 'john@example.com' },
//   { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
// ]

Complete Example

Here’s a complete example putting it all together:

import { parseYaml } from '@mockmaster/openapi'
import { generateScenariosFromSpec, writeScenario } from '@mockmaster/cli'
import { createReplayHandler } from '@mockmaster/msw-adapter'
 
async function main() {
  // 1. Parse OpenAPI spec
  const spec = parseYaml(`
    openapi: 3.0.0
    info:
      title: User API
      version: 1.0.0
    paths:
      /users:
        get:
          responses:
            '200':
              content:
                application/json:
                  schema:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: integer }
                        name: { type: string }
                        email: { type: string, format: email }
  `)
 
  // 2. Generate scenarios
  const scenarios = generateScenariosFromSpec(spec, 'user-api')
 
  // 3. Save to disk (optional)
  await writeScenario('./scenarios', scenarios[0])
 
  // 4. Use in tests
  const handler = createReplayHandler(scenarios[0])
  const response = handler({ method: 'GET', path: '/users' })
 
  console.log('✓ Scenario created and tested successfully!')
  console.log('Response:', response.body)
}
 
main().catch(console.error)

Using in Tests

Vitest Example

import { describe, it, expect, beforeEach } from 'vitest'
import { readScenario } from '@mockmaster/cli'
import { createReplayHandler } from '@mockmaster/msw-adapter'
 
describe('User API', () => {
  let handler: ReturnType<typeof createReplayHandler>
 
  beforeEach(async () => {
    const scenario = await readScenario('./scenarios', 'user-api')
    handler = createReplayHandler(scenario)
  })
 
  it('fetches users', () => {
    const response = handler({ method: 'GET', path: '/users' })
 
    expect(response.status).toBe(200)
    expect(response.body).toBeInstanceOf(Array)
    expect(response.body[0]).toMatchObject({
      id: expect.any(Number),
      name: expect.any(String),
      email: expect.stringMatching(/@/)
    })
  })
})

Jest Example

import { readScenario } from '@mockmaster/cli'
import { createReplayHandler } from '@mockmaster/msw-adapter'
 
describe('User API', () => {
  let handler: ReturnType<typeof createReplayHandler>
 
  beforeEach(async () => {
    const scenario = await readScenario('./scenarios', 'user-api')
    handler = createReplayHandler(scenario)
  })
 
  test('fetches users', () => {
    const response = handler({ method: 'GET', path: '/users' })
 
    expect(response.status).toBe(200)
    expect(response.body).toBeInstanceOf(Array)
  })
})

Next Steps

Now that you have MockMaster up and running:

  1. Learn the fundamentals: Read about Core Concepts
  2. Explore packages: Check out the API Packages documentation
  3. Integrate with your framework: See Testing Guides for Vitest, Jest, and Playwright
  4. Browse examples: View Examples for more complex scenarios

Common Questions

Do I need to use OpenAPI?

No! While OpenAPI integration is convenient, you can manually create recordings:

import { createScenario, createRecording, addRecordingToScenario } from '@mockmaster/msw-adapter'
 
let scenario = createScenario('manual-api', 'Manually created scenario')
 
const recording = createRecording(
  { method: 'GET', url: 'https://api.example.com/users', path: '/users', timestamp: Date.now() },
  { status: 200, body: [{ id: 1, name: 'John' }], timestamp: Date.now() }
)
 
scenario = addRecordingToScenario(scenario, recording)

Can I use MockMaster without TypeScript?

Yes! MockMaster works with JavaScript, but you’ll miss out on the type safety and IntelliSense features.

How do I handle authentication?

Check out the Authentication Flow Mocking example.

InstallationOverview