Scenario based API mocking with `ng-apimock`

Overview

ng-apimock is a tool that provides scenario based API mocking. It can be used to test and develop applications without the need of a backend. Alternatively you can also chose to let certain calls through to the actual backend and apply mocking selectively.

Overview
Core concepts
How it works
Starting the mock server
TypeScript
Writing mocks
Dependencies

Core concepts

Most files used for implementing ng-apimock in this workspace are located in the ./ng-apimock folder. This makes it easy to locate and change files.
Configuration and further functionality for ng-apimock can be found in ./ng-apimock/start-ng-apimock.ts
Mock files are located in ./ng-apimock/mocks, this will be picked up by the mock server when started.
Scripts inside of package.json tie the steps together to give you a runnable command, which starts your app and the mock server

How it works

To make make fetch calls in your Angular app and use mocked values, use the environment variables of your app. This way you can inject the right values required for each environment. For use with the mocking server you can follow these steps.

Make fetch calls as follows:

import { HttpClient } from '@angular/common/http';
import { Injectable } from '@angular/core';
import type { Observable } from 'rxjs';
import { MyResponseType } from './types';

@Injectable({
  providedIn: 'root',
})
export class MyService {
  public constructor(private readonly http: HttpClient) {}

  public fetchData(): Observable<MyResponseType[]> {
    return this.http.get<MyResponseType[]>('my-endpoint');
  }
}

Register your mock endpoint in ng-apimock/proxy.conf.json. Calls to this endpoint will now be proxied to the port where the ng-apimock server is running.

{
    "/my-endpoint": {
      "target": "http://localhost:9000",
      "secure": false,
      "logLevel": "debug"
    }
  }

To use the environment variable when starting your app, add it to your project.json

{
  "targets": {
    "serve": {
      // This setting will be used to run your app using the build command 'build:mock'
      "mock": {
        "proxyConfig": "ng-apimock/proxy.conf.json",
        "browserTarget": "<your-app>:build:development"
      }
    }
  }
}

In order to start the mock server you will need a startup script: ng-apimock/start-ng-apimock.ts

Starting the mock server

Dependencies

Before getting started, make sure to install the necessary dependencies by running: npm install

Make sure the folling dependencies are added to your package.json file:

@ng-apimock/core
@ng-apimock/dev-interface
ts-node
concurrently

package.json

  "scripts": {
    "mock:serve": "ts-node ./ng-apimock/start-ng-apimock.ts",
    "<my-app>:serve:mock": "nx run <my-app> --configuration=mock",
    "<my-app>:serve:start:mock": "concurrently --kill-others \"npm run mock:serve\" \"npm run <my-app>:serve:mock\""
  },

After executing npm run mock:serve:<my-app>:mock command, you should see the following output in your terminal:

[HPM] Proxy created: /  -> my-endpoint
[0] [HPM] Proxy rewrite rule created: "^/my-endpoint" ~> ""
[0] @ng-apimock/core running on http://localhost:9000
[0] @ng-apimock/dev-interface is available under http://localhost:9000/dev-interface
[1] ** Angular Live Development Server is listening on localhost:4201, open your browser on http://localhost:4200/ **

This confirms that both the app and the mock server were started successfully and the proxies were configured correctly.

From here you can go to http://localhost:9000/dev-interface and see an overview of your mocked endpoints and can select scenarios, add delay and much more. Read more about the dev-interface here.

TypeScript

We can write typesafe mocks that adhere to the ng-apimock schema and give warnings when incorrect properties are provided.

Here is part of the top level TypeScript interface for the ng-apimock schema:

export interface NgAPIMockSchema<T> {
  name: string;
  isArray?: boolean;
  delay?: number;
  request: MockRequest;
  responses: Record<string, MockResponse<T>>;
}

export interface MockRequest {
  url: string;
  method: 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'POST' | 'PUT';
  body?: Record<string, unknown>;
  headers?: Record<string, unknown>;
}

export interface MockResponse<T> {
  data: T | null;
  default?: boolean;
  file?: string;
  headers?: Record<string, string>;
  status?: number;
  statusText?: string;
  then?: MockResponseThenClause;
}
export interface MockResponseThenClause {
  criteria?: MockResponseThenClauseCriteria;
  mocks: [
    MockResponseThenClauseMockSelection,
    ...MockResponseThenClauseMockSelection[]
  ];
}
export interface MockResponseThenClauseCriteria {
  times: number;
}
export interface MockResponseThenClauseMockSelection {
  name?: string;
  scenario: string;
}

Note: NgAPIMockSchema accepts a generic type that lets you pass the desired type of your API response and assigns it to data

Writing mocks

As mentioned above, mocks are written in TypeScript and can be found in ng-apimock/mocks. Mock files contain scenarios for a single endpoint and a single HTTP method, which means a *.mock.ts file can be viewed as a collection of scenarios.

For topics such as advanced request matching, chaining responses or returning file data please read the ng-apimock documentation.

For now, here are a few conventions that will help us keep things neat and organized:

Please make a folder for the service you are mocking.
Please use this naming convention: <HTTP method>-<my-endpoint>.mock.ts, e.g. GET-my-endpoint.mock.ts
Consider keeping the name of the mocks module.export the same, and let it reflect the service, endpoint and method it applies to. So for example GETmyEndpoint
It's advised to use part of the HTTP messages as a starting point in your naming, so consider names like ok, notFound or internalServerError

Example mock where data will be of type MyResponseType[]. It has the following scenarios:

ok
created
internalServerError

ng-apimock/mocks/my-api/GET-my-endpoint.mock.ts

import { NgAPIMockSchema } from '../ng-apimock.model';
import { MyResponseType } from './types';

const GETmyEndpoint: NgAPIMockSchema<MyResponseType[]> = {
  name: 'GETmyEndpoint',
  request: {
    url: '/my-endpoint',
    method: 'GET',
  },
  responses: {
    ok: {
      default: true,
      status: 200,
      data: []// mock data for the scenario 'ok' goes here
    },
    created: {
      default: false,
      status: 201,
      data: []// mock data for the scenario 'created' goes here
    },
    internalServerError: {
      default: false,
      status: 500,
      data: null // can also be 'null'
    },
  },
};

module.exports = GETmyEndpoint;

florestankorp/README.md

Scenario based API mocking with ng-apimock