Mirage JS GraphQL

npm package build

Overview

Mirage lets you simulate API responses by writing route handlers. A route handler is a function that returns data to fulfill a request. Mirage GraphQL provides the ability to create a GraphQL route handler based on your GraphQL and Mirage schemas.

import { createServer } from "miragejs"
import { createGraphQLHandler } from "@miragejs/graphql"
import graphQLSchema from "app/gql/schema.gql"

export default function makeServer(config) {
  return createServer({
    routes() {
      const graphQLHandler = createGraphQLHandler(graphQLSchema, this.schema)

      this.post("/graphql", graphQLHandler)
    }
  })
}

Highlights

Mirage GraphQL tries to do a lot for you. Here are the highlights:

It fulfills GraphQL requests by fetching data from Mirage's database.
It filters records from Mirage's database by using arguments from your GraphQL queries.
It handles create, update and delete type mutations automatically based on some conventions.
It allows you to supply your own resolvers (for cases where the automatic query and mutation resolution isn't sufficient).

Installation

You should install both miragejs and @miragejs/graphql.

# Using npm
npm install --save-dev miragejs @miragejs/graphql

# Using Yarn
yarn add --dev miragejs @miragejs/graphql

Guide

This guide assumes most of its readers are already using GraphQL in their apps and want to start using Mirage to mock out their backend. This guide will try to provide enough information to be useful but it's worth reading the Mirage guides to get a full understanding of everything Mirage can do.

Mirage GraphQL Assumptions
Example Use Cases

Mirage GraphQL Assumptions

There are a couple of assumptions Mirage GraphQL makes concerning how it resolves GraphQL queries. It's important to understand these assumptions to avoid confusion based on its behavior.

You Don't Need to Define Mirage Models

In many cases, you need to tell Mirage about the models that exist in your app but Mirage GraphQL assumes relationships between types from your GraphQL schema and creates models accordingly. You can still define Mirage models, if you'd like, and Mirage GraphQL won't try to create them on its own.

Arguments from GraphQL Queries Map to Field Names of the Return Type

Mirage GraphQL uses arguments to filter records from Mirage's database. This isn't very useful for testing, as you only need to seed Mirage's database with the exact records you need for a given test. It's more useful when using Mirage for development where filtering and pagination may be desired for a more realistic user experience.

Miscellaneous Assumptions

Fields that should resolve to a single object of a union type are resolved by taking the first appropriate record from Mirage's database. This is how Mirage GraphQL automatically resolves in this scenario. As with all automatic resolution, if you need to include some additional logic, you'll need to supply your own resolver.

Example Use Cases

Notes:

For further reference, there are many more use cases covered by the integration tests.
The graphql-request library is used in the examples but is not a dependency installed by Mirage GraphQL.

Example Schema

For these examples, imagine we have a GraphQL schema that looks like this:

# app/gql/schema.gql

input PersonInput {
  firstName: String
  lastName: String
}

type Mutation {
  createPerson(input: PersonInput!): Person
  updatePerson(id: ID!, input: PersonInput!): Person

  # Note: `deletePerson` can't automatically be resolved due to the Boolean
  # return type. We will need to implement a resolver for this.
  deletePerson(id: ID!): Boolean
}

type Person {
  id: ID!
  firstName: String!
  lastName: String!
}

type Query {
  allPeople: [Person]
  person(id: ID!): Person

  # Note: `people` can't automatically be resolved if the `sortBy` argument is
  # supplied to the query. We will need to implement a resolver for this.
  people(firstName: String, lastName: String, sortBy: String): [Person]
}

and we create a Mirage server like this:

// app/mirage/server.js

import { createServer } from "miragejs"
import { createGraphQLHandler } from "@miragejs/graphql"
import graphQLSchema from "app/gql/schema.gql"

export function makeServer() {
  return createServer({
    routes() {
      const graphQLHandler = createGraphQLHandler(graphQLSchema, this.schema)

      this.post("/graphql", graphQLHandler)
    }
  })
}

Example: Find Person by ID

In this example, we can get a Person record by ID.

// app/components/person.js

import { createServer } from "app/mirage/server"
import { request } from "graphql-request"

const server = createServer()

server.create("person", { firstName: "Mikael", lastName: "Åkerfeldt" })

export default {
  // ...other component stuff

  personQuery: `
    query Person($id: id) {
      person(id: $id) {
        id
        firstName
        lastName
      }
    }
  `,
  getPerson(id) {
    return request("/graphql", this.personQuery, { id })
  }
}

A call to getPerson("1") will cause Mirage GraphQL to respond with:

{
  "data": {
    "person": {
      "id": "1",
      "firstName": "Mikael",
      "lastName": "Åkerfeldt"
    }
  }
}

Example: Get All People

In this example, we can get all the Person records from Mirage's database.

// app/components/people.js

import { createServer } from "app/mirage/server"
import { request } from "graphql-request"

const server = createServer()

server.create("person", { firstName: "Mikael", lastName: "Åkerfeldt" })
server.create("person", { firstName: "Per", lastName: "Nilsson" })
server.create("person", { firstName: "Tomas", lastName: "Haake" })

export default {
  // ...other component stuff

  peopleQuery: `
    query People {
      people {
        id
        firstName
        lastName
      }
    }
  `,
  getPeople() {
    return request("/graphql", this.peopleQuery)
  }
}

A call to getPeople() will cause Mirage GraphQL to respond with:

{
  "data": {
    "people": [
      {
        "id": "1",
        "firstName": "Mikael",
        "lastName": "Åkerfeldt"
      },
      {
        "id": "2",
        "firstName": "Per",
        "lastName": "Nilsson"
      },
      {
        "id": "3",
        "firstName": "Tomas",
        "lastName": "Haake"
      }
    ]
  }
}

Example: Creating and Updating a Person

In this example, we can create or update a Person record in Mirage's database.

// app/components/people.js

import { createServer } from "app/mirage/server"
import { request } from "graphql-request"

const server = createServer()

export default {
  // ...other component stuff

  createPersonMutation: `
    mutation CreatePerson($input: PersonInput!) {
      createPerson(input: $input) {
        id
        firstName
        lastName
      }
    }
  `,
  updatePersonMutation: `
    mutation UpdatePerson($id: ID!, $input: PersonInput!) {
      updatePerson(id: $id, input: $input) {
        id
        firstName
        lastName
      }
    }
  `,
  createPerson(input) {
    return request("/graphql", this.createPersonMutation, { input })
  },
  updatePerson(id, input) {
    return request("/graphql", this.updatePersonMutation, { id, input })
  }
}

A call to createPerson({ firstName: "Ola", lastName: "Englund" }) will cause Mirage GraphQL to respond with:

{
  "data": {
    "createPerson": {
      "id": "1",
      "firstName": "Ola",
      "lastName": "Englund"
    }
  }
}

If you then wanted to update that person, you could call updatePerson("1", { lastName: "Strandberg" }) which would result in:

{
  "data": {
    "updatePerson": {
      "id": "1",
      "firstName": "Ola",
      "lastName": "Strandberg"
    }
  }
}

Automatic Mutation Conventions

Mirage GraphQL will automatically resolve these mutations per these conventions:

A mutation that returns an object type and has one argument, an input type, will create a record with the given input type attributes.
A mutation that returns an object type and has two arguments, an ID type and an input type, will update a record having that ID with the given input type attributes.
A mutation that returns an object type and has one argument, an ID type, will delete a record having that ID.

Any other combination of arguments for a mutation requires a resolver. This can be seen in a later example.

Example: Filtering People

In this example, we can get filter Person records from Mirage's database. There will be two part

Graphql

Install / Use

README