specmatic

Specmatic Framework Node Module

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

• Easy installation and upgrade of the jar file in node projects through npm
• Global install using npm and easy run specmatic jar executable without having to download the jar file and having to run java -jar
• Programmatic access to some of the specmatic options as api like start / stop the stub server, setting expecations, running tests. These helpers methods can be used in a javascript project programmatically instead of using cli scripts.

Table Of Contents

• Quick Start
• Contract as Stub / Smart Mock (For API clients / consumers)
• Contract as Test (For API Providers / Service)
• Sample Repo
• Programmatic Access
  • Core APIs
  • Kafka APIs
• IDE Support
  • Jest Framework
• Logging
• Known Issues
  • 1. Node 17/18 - Connection Refused error when connecting to stub
  • 2. Error "ReferenceError: setImmediate is not defined"
  • 3. Specmatic stub is not terminated after test execution
  • 4. Test results don't show up in IDE
• Contribution

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

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 {
    startHttpStub,
    setHttpStubExpectationJson,
    setHttpStubExpectations,
    stopHttpStub,
    test,
    showTestResults,
    printJarVersion,
    startKafkaMock,
    setKafkaMockExpecations,
    stopKafkaMock,
    verifyKafkaMock
} from 'specmatic';

Core APIs

startHttpStub(host?: string, port?: number, args?: (string | number)[]): Promise<Stub>
Start the stub server. Argument args values are passed directly to specmatic jar executable.
Note: This replaces startStub method which is deprecated

setHttpStubExpectationJson(stubResponse: any, stubServerBaseUrl?: string): Promise<boolean>
Set stub expectation from a static JSON object. Stub should be running before invoking this method.

setHttpStubExpectations(stubPath: string, stubServerBaseUrl?: string): Promise<boolean>
Set stub expectation from a file. Stub should be running before invoking this method.
Note: This replaces setExpectations method which is deprecated

stopHttpStub(stub: Stub)
Stop the stub server
Note: This replaces stopStub method which is deprecated

test(host?: string, port?: string, contractPath?: string, args?: (string | number)[]): Promise<{ [k: string]: number } | undefined>
Run tests. Argument args values are passed directly to specmatic jar executable.

showTestResults(testFn: (name: string, cb: () => void) => void)
View test results in any framework so that it shows up in IDE specific test results interface. Refer IDE Support below for details on how to use this feature.

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

enableApiCoverage(expressAppRef)
enable api coverage for express apps to know which apis and http verbs are covered in contract tests and which not

Kafka APIs

startKafkaMock(port?: number, args?: (string | number)[]): Promise<KafkaStub>
Start kafka stub. Requires an OpenAPI kafka spec in specmatic.json.
Note: This replaces startKafkaStub method which is deprecated

setKafkaMockExpectations(stub: KafkaStub, expecations: any): Promise<void>
Set expected message count on Kafka for each topic. Expecations are of the format

[
    {
        "topic": "product-queries",
        "count": 2
    },
    {
        "topic": "test-topic",
        "count": 2
    }
]

Note: This replaces setKafkaStubExpectations method which is deprecated

stopKafkaMock(stub: KafkaStub)
Stop a running kafka stub.
Note: This replaces stopKafkaStub method which is deprecated

verifyKafkaMock(stub: KafkaStub): Promise<Boolean>
Verify all expecations set on Kafka.
Note: This replaces verifyKafkaStub method which is deprecated

verifyKafkaMockMessage(stub: KafkaStub, topic: string, value: string): Promise<Boolean>
Verify kafka message. This is invoked in tests to check on kafka side if a message expected to by pushed by a BFF api is recieved by Kafka. The Kafka stub starts a verification end point for this purpose which is invoked internally by this api..
Note: This replaces verifyKafkaStubMessage method which is deprecated

IDE Support

Specmatic tests can be displayed in IDE specific test result view by using showTestResults method coupled with test method. Test framework specific steps are below.

Jest Framework

Example: https://github.com/znsio/specmatic-order-bff-nodejs/blob/main/test/contract

1. Call test method in a globalSetup script. globalSetup script path can be set either in the jest command line argument or in jest configuration file.
2. Call showTestResults in the root of your test file anywhere. You can pass test method of Jest as its argument and it works out of the box.

Note 1: Since you are running test method in a globalSetup script, any pre-test setup like starting a stub server, app server and any dependent processes like redis server has to be done in the globalSetup script in required sequence before test method is called.

Note 2: If your project already has a jest globalSetup and or globalTeardown scripts then reuse them but include the necessary code to make IDE integration work.

Note 3: If your project uses jest projects support (--projects), then configure globalSetup/globalTeardown in the project specific jest config file

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

Known Issues

1. 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.

2. Error "ReferenceError: setImmediate is not defined"

This happens due to an issue in Jest framework. The easiest solution is to import core-js in the affected test file.

3. Specmatic stub is not terminated after test execution

This happens if stub is not stopped in the same way it is started. There can be two possibilities in case of Jest framework

1. If started from before* methods in a test suite, then it should be stopped using stopStub method in corresponding after* method
2. If started using globalSetup script, then it should be stopped in a globalTeardown script

Note: If bail is set to true in jest config, then any test failure will abort further execution of tests including after* methods and globalTeardown script. This will prevent stopping your stubs and other processes leaving them hanging and causing port conflicts when tests are run again next.

4. Test results don't show up in IDE

We have tested IDE integration with webstorm and jest framework combination. Visual Studio Code seems to work on and off with Jest. Please follow the instructions mentioned in IDE Support to set this up.

Any other test framework can easily be also configured to display test results in IDE test results view by passing a convertor function to the showTestResults api.

Contribution

Please refer to this link