specmatic 0.68.5 → 0.69.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +58 -16
  2. package/package.json +1 -1
  3. package/specmatic.jar +0 -0
package/README.md CHANGED
@@ -4,10 +4,26 @@
4
4
  [![publish](https://github.com/znsio/specmatic-node/actions/workflows/publish.yml/badge.svg)](https://www.npmjs.com/package/specmatic)
5
5
  [![release](https://badgen.net/github/release/znsio/specmatic-node/master)](https://github.com/znsio/specmatic-node/releases/latest)
6
6
 
7
- This node module is a thin wrapper over the [standalone executable jar](https://specmatic.in/getting_started.html#setup). All core capabilities are in the main [Specmatic project](https://github.com/znsio/specmatic). The purpose of this wrapper module is to act as a convenience to help with below aspects.
8
-
9
- - Easy installation and upgrade of the jar file in node projects through npm
10
- - 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.
7
+ This node module is a thin wrapper over the [specmatic executable jar](https://specmatic.in/getting_started.html#setup). All core capabilities are in the main [Specmatic project](https://github.com/znsio/specmatic). The purpose of this wrapper module is to act as a helper with below aspects.
8
+
9
+ - Easy installation and upgrade of the jar file in node projects through npm
10
+ - Global install using npm and easy run specmatic jar executable without having to download the jar file and having to run `java -jar`
11
+ - 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.
12
+
13
+ ## Table Of Contents
14
+ - [Quick Start](#quick-start)
15
+ - [Contract as Stub / Smart Mock (For API clients / consumers)](#contract-as-stub--smart-mock-for-api-clients--consumers)
16
+ - [Contract as Test (For API Providers / Service)](#contract-as-test-for-api-providers--service)
17
+ - [Sample Repo](#sample-repo)
18
+ - [Programmatic Access](#programmatic-access)
19
+ - [IDE Support](#ide-support)
20
+ - [Jest Framework](#jest-framework)
21
+ - [Logging](#logging)
22
+ - [Known Issues](#known-issues)
23
+ - [1. Node 17/18 - Connection Refused error when connecting to stub](#1-node-1718---connection-refused-error-when-connecting-to-stub)
24
+ - [2. Error "ReferenceError: setImmediate is not defined"](#2-error-referenceerror-setimmediate-is-not-defined)
25
+ - [3. Specmatic stub is not terminated after test execution](#3-specmatic-stub-is-not-terminated-after-test-execution)
26
+ - [4. Test results don't show up in IDE](#4-test-results-dont-show-up-in-ide)
11
27
 
12
28
  ## Quick Start
13
29
 
@@ -23,10 +39,6 @@ In stub mode, Specmatic emulates the Provider / API / Service based on the API S
23
39
 
24
40
  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](https://specmatic.in/#contract-as-test)
25
41
 
26
- ## API
27
-
28
- Check [Documentation](https://specmatic.in/documentation.html) for more information on cli commands and arguments.
29
-
30
42
  ## Sample Repo
31
43
 
32
44
  https://github.com/znsio/specmatic-order-bff-nodejs
@@ -47,23 +59,39 @@ import {
47
59
  ```
48
60
 
49
61
  `startStub(host?: string, port?: string, stubDir?: string) : Promise<ChildProcess>` <br />
50
- method to start the stub server.
62
+ Start the stub server
51
63
 
52
64
  `stopStub(process: ChildProcess)` <br />
53
- method to stop the stub server.
65
+ Stop the stub server
54
66
 
55
67
  `test(host?: string, port?: string, specs?: string): Promise<boolean>` <br />
56
- method to run tests.
68
+ Run tests
57
69
 
58
70
  `setExpectations(stubPath: string, stubServerBaseUrl?: string): Promise<boolean>` <br />
59
- method to dynamically set stub expectiona. Stub should be running before invoking this method.
71
+ Set stub expectiona. Stub should be running before invoking this method.
60
72
 
61
73
  `showTestResults(testFn: (name: string, cb: () => void) => void)` <br />
62
- method to report test results in any framework so that it shows up in IDE test results interface.
74
+ View test results in any framework so that it shows up in IDE specific test results interface. Refer [IDE Support](#ide-support) below for details on how to use this feature.
63
75
 
64
76
  `printJarVersion()` <br />
65
77
  method to print the version of specmatic.jar
66
78
 
79
+ ## IDE Support
80
+
81
+ 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.
82
+
83
+ ### Jest Framework
84
+ Example: https://github.com/znsio/specmatic-order-bff-nodejs/blob/main/test/contract
85
+
86
+ 1. Call `test` method in a [`globalSetup`](https://jestjs.io/docs/configuration#globalsetup-string) script. `globalSetup` script path can be set either in the jest command line argument or in jest configuration file.
87
+ 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.
88
+
89
+ *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.
90
+
91
+ *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.
92
+
93
+ *Note 3:* If your project uses jest projects support ([`--projects`](https://jestjs.io/docs/configuration#projects-arraystring--projectconfig)), then configure `globalSetup/globalTeardown` in the project specific jest config file
94
+
67
95
  ## Logging
68
96
 
69
97
  By default only warning and error messages are displayed. You can configure the loglevel in package.json as
@@ -74,14 +102,28 @@ By default only warning and error messages are displayed. You can configure the
74
102
  },
75
103
  ```
76
104
 
77
- logLevel accepts all values supported by winston logger (https://github.com/winstonjs/winston#logging-levels)
105
+ logLevel accepts all values supported by [winston logger](https://github.com/winstonjs/winston#logging-levels)
78
106
 
79
107
  ## Known Issues
80
108
 
81
- ### Node 17/18 - Connection Refused error when connecting to stub
109
+ ### 1. Node 17/18 - Connection Refused error when connecting to stub
82
110
 
83
111
  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`.
84
112
 
85
- ### Error `ReferenceError: setImmediate is not defined`
113
+ ### 2. Error "ReferenceError: setImmediate is not defined"
86
114
 
87
115
  This happens due to an issue in Jest framework. The easiest solution is to import `core-js` in the affected test file.
116
+
117
+ ### 3. Specmatic stub is not terminated after test execution
118
+
119
+ This happens if stub is not stopped in the same way it is started. There can be two possibilities in case of *Jest* framework
120
+ 1. If started from `before*` methods in a test suite, then it should be stopped using `stopStub` method in corresponding `after*` method
121
+ 2. If started using `globalSetup` script, then it should be stopped in a `globalTeardown` script
122
+
123
+ *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.
124
+
125
+ ### 4. Test results don't show up in IDE
126
+
127
+ 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](#ide-support) to set this up.
128
+
129
+ 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specmatic",
3
- "version": "0.68.5",
3
+ "version": "0.69.0",
4
4
  "description": "Node wrapper for Specmatic",
5
5
  "main": "dist/index.js",
6
6
  "scripts": {
package/specmatic.jar CHANGED
Binary file