znsio / specmatic-order-bff-nodejs

Specmatic project to demonstrate in nodejs how to stub http APIs with their OpenAPI specifications and mock Kafka broker with AsyncAPI specification

Specmatic Sample: NodeJS BFF calling Domain API

• Specmatic Website
• Specmatic Documenation

This sample project demonstrates how we can practice contract-driven development and contract testing in a NodeJS application that depends on an external domain service and Kafka. Here, specmatic is used to stub calls to domain API service based on its OpenAPI spec and mock Kafka based on its AsyncAPI spec.

Here is the OpenAPI spec of the domain API that defines the API endpoints, its request parameters and response along with their schema.

Here is the AsyncAPI spec of Kafka that defines the topics and message schema.

Definitions

• BFF: Backend for Front End
• Domain API: API managing the domain model
• Specmatic Stub/Mock Server: Create a server that can act as a real service using its OpenAPI or AsyncAPI spec

Background

A typical web application might look like this. We can use Specmatic to practice contract-driven development and test all the components mentioned below. In this sample project, we look at how to do this for nodejs BFF which is dependent on Domain API Service and Kafka demonstrating both OpenAPI and AsyncAPI support in specmatic.

Tech

1. NodeJS + Express
2. Specmatic
3. Specmatic Beta extension (for mocking Kafka)
4. Jest & SuperTest

Start BFF Application

This will start the main nodejs application providing backend service for frontend (BFF)

npm start

Access find orders API at http://localhost:8080/findAvailableProducts. This is used to demo HTTP stubbing using OpenAPI and Kafka mocking using AsyncAPI
Note: Unless domain API service and Kafka mocks are running, the above requests will fail. Move to the next section for the solution!

Start BFF Server with Dependencies (Domain API Stub and Kafka Mock Servers)

This will start the nodejs based BFF server with domain API stubbed using Specmatic HTTP stub server and Kafka mocked using Specmatic Kafka mock server to demonstrate workings of the stub server

npm run startWithDeps

Access find orders API again at http://localhost:8080/findAvailableProducts with a result like

[{"id":698,"name":"NUBYR","type":"book","inventory":278}]

Run Tests

This will start the Specmatic HTTP stub server for domain API and Specmatic Kafka mock server using the information in specmatic.json and run tests to validate BFF APIs.

npm run test-ci

Troubleshooting

1. Specmatic contract tests don't show up in VSCode Test Explorer

   Specmatic is tested with projects using Jest framework. If you are using any other framework then let us know and we will revert with a solution. In case of jest, if contract tests don't show up, then try restarting the jest runners

2. Specmatic contract tests don't run in Jetbrain's PhpStorm

   Jetbrain's PhpStorm does not read test script in package.json to determine the command to run tests. It instead uses its own interface to configure all the options. You can configure the same options in the test script in package.json, in PhpStorm's test run configuration as below

   • test script in package.json

   {
       ...
       "test": "cross-env NODE_OPTIONS=--experimental-vm-modules NODE_NO_WARNINGS=1 node --experimental-vm-modules ./node_modules/.bin/jest --collectCoverage --detectOpenHandles"
       ...
   }

   • Above configured in PhpStorm