Stateful Mock Server: One Library to Mock Them All

While there are many tools available that assist with mocking, at least when it comes to GraphQL, none of them supports a very desirable feature: statefulness. We at Bitovi went on a mission to create a tool to mock with ease and speed while using XState to maintain stateful flexibility.

Currently supporting only GraphQL, but with plans for OpenAPI in the future, we are proud to announce the release of Stateful Mock Server!

What Is Stateful Mock Server?

Stateful Mock Server (SMS) is an npm package that mocks a GraphQL API server. You don’t even need to know GraphQL or programming. All you need to get it running is a schema.graphql file from your project.

Out of the box, it generates some default random data. To customize the state to better match your app, you customize a .json file that we generate for you. Stateful Mocks picks up on changes you make to the file during runtime and dynamically updates the server.

Why Would You Use It?

Mocking tools are useful for every project. They increase development speed by providing data that conforms to a specified interface, which minimizes the wait for backend development in order to start developing features.

Every developer eventually mocks. Be it entirely by hand, with an already available option (like mock server, for GraphQL) or with stack-specific tools. Mocking is a very important part of development. Stateful Mocks’ goal is to be the best tool for most cases thanks to its flexibility and ease of use. Some of the things it does best include:

• Helping with your tests for CI/CD flows
• Generating quick data for an entity with our CLI
• Generating stateless mock data that matches your GraphQL schema
• Generating stateful mocked data that conforms to your project’s rules, as defined in your configuration’s .json
• Making the process of mocking more uniform throughout your company

How to Be an Expert Mocker

You don’t need previous mocking knowledge to use SMS! You just need to have Node installed on your computer, a code editor, and a folder with a GraphQL schema.

If you want a more complete tutorial or want to learn how to deeply customize your Stateful Mocks server, refer to the documentation.

To quickly get started with SMS, you can use the sms init CLI command and have a working mock server in under 3 minutes. With Node installed, run these commands:

1. To install Node, go to Download | Node.js
   - If you need a code editor, we recommend Visual Studio
2. Create a folder and open it up in your code editor.
3. Initialize an NPM project in the folder by running: npm init -y.
4. Install stateful-mocks as a dev dependency with the command: npm install @bitovi/stateful-mocks -D
5. Run the command: npx sms init Stateful-mock’s CLI will ask you questions regarding your configuration. For the purpose of getting a quick setup, you may choose the default answer for the following:

• • Config file path?
  • Schema file path?
  • Port number?

The last question will be a list of options:

• Choose a starting config:
  • Empty
  • User Admin

Select User Admin.

After answering the last question, the generator will create files for graphql.schema and config.json with an example set of rules. It also adds a package.json script for initializing the SMS server.

6. Run the sms script: npm run sms to start Stateful Mocks Server. This will spawn a GraphQL server under the hood that you can use to run real requests! You’ll be able to make requests to the outputted URL just like in a regular GraphQL server! Have fun.

Making Requests

Thanks to Apollo Server you can make requests from your browser, so nothing else is needed to test your Stateful Mocks server (though you may use any other tool you want).

Your First Query

Open Apollo Studio, paste the following query into the “Operation” area, and the variables in the next code snippet into the “Variables” area at the bottom of the Apollo Studio utility.

query AccountById($accountByIdId: Int) {
  accountById(id: $accountByIdId) {
    id
    name
    email
    password
    token
  }
}

Here are the variables

{
  "accountByIdId": 1
}

You’ll get back as result the values for it defined in your mocks/config.json. In our case it is a null value, because in our hypothetical server the user doesn’t start as “created”

"data": {
    "accountById": null
  }
}

Make a Mutation

Now let’s try a mutation. Click the + button inside Apollo Studio to open a new tab, then paste this mutation and the variables in the next snippet down

mutation Mutation($input: CreateAccountInput!) {
  createAccount(input: $input) {
    id
    name
    email
    password
    token
  }
}

Here are the variables for the mutation

{
  "input": {
    "name": "John Doe",
    "email": "john@mail.com",
    "password": "johnPass"
  }
}

Our mutation will transition this instance’s state to “created”, as per defined in the config.json, and we’ll get data back

{
  "data": {
    "createAccount": {
      "id": 1,
      "name": "John Doe",
      "email": "john@mail.com",
      "password": "johnPass",
      "token": null
    }
  }
}

Query Again and Get Data

Now if you try to repeat the initial query, instead of null, you should get a response like this

{
  "data": {
    "accountById": {
      "id": 1,
      "name": "John Doe",
      "email": "john@mail.com",
      "password": "johnPass",
      "token": null
    }
  }
}

Happy Mocking!

Take advantage of Stateful Mock Server in your next project. You can read the full documentation at Stateful Mock Server, where you can get a more complete overview of the “User Admin” quick start, and learn how to customize the config and underlying XState machine.