Specmatic Framework Node Module

This node module is a thin wrapper over the standalone executable jar. All core capabilities are in the main Specmatic project. The purpose of this wrapper module is to act as a convenience to help with below aspects.

• Easy installation and upgrade of the jar file in node projects through npm
• JS helper library which provides to do various setup steps like start, stop the specmatic stub server, installing specs etc. These helpers methods can be used inside a setup file inside a javascript project programmatically instead of using cli scripts.

Quick Start

npm install specmatic will install the specmatic locally to the node project.

Sample npm scripts to run specmatic, (Check Documentation for more information on cli commands and arguments.)

Contract as Stub / Smart Mock (For API clients / consumers)

In stub mode, Specmatic emulates the Provider / API / Service based on the API Specification so that the consumer / client application can make independent progress. Learn more.

Contract as Test (For API Providers / Service)

Tests for Free – Specmatic parses your API Specification files and based on this generates requests which are fired at your application. It then verifies if your application’s response is as per your API Specification. All this with a “No Code” approach.. Learn More

API

Check Documentation for more information on cli commands and arguments.

Sample Repo

https://github.com/znsio/specmatic-order-bff-nodejs

Programmatic Access

Specmatic JS library exposes some of the commands as methods that can be run programmatically from any javascript testing framework, during setup or test phases.

import {
    startStub,
    stopStub,
    test,
    setExpecations,
    showTestResults,
    printJarVersion
} from 'specmatic';

startStub(host?: string, port?: string, stubDir?: string) : Promise<ChildProcess>
method to start the stub server.

stopStub(process: ChildProcess)
method to stop the stub server.

test(host?: string, port?: string, specs?: string): Promise<boolean>
method to run tests.

setExpectations(stubPath: string, stubServerBaseUrl?: string): Promise<boolean>
method to dynamically set stub expectiona. Stub should be running before invoking this method.

showTestResults(testFn: (name: string, cb: () => void) => void)
method to report test results in any framework so that it shows up in IDE test results interface.

printJarVersion()
method to print the version of specmatic.jar

Logging

By default only warning and error messages are displayed. You can configure the loglevel in package.json as

"specmatic": {
    "logLevel": "debug"
},

logLevel accepts all values supported by winston logger (https://github.com/winstonjs/winston#logging-levels)

Known Issues

Node 17/18 - Connection Refused error when connecting to stub

Node 18 apparently shifted to IPv6 as first choice for resolving hostname when both IPv4 and IPv6 addresses are available. This means localhost most likely resolves to ::1 rather than 127.0.0.1 or 0.0.0.0. Now specmatic node wrapper does not start the stub server but the java program under the hood does it and java still resolves to IPv4 address by default. Thus localhost on node v18 and java might resolve to a different address and any connection from node to the running stub will fail. To resolve this, until we have a permanent solution, we request to disable any IPv6 address mapping to a named host in your DNS resolver or /etc/hosts.