specshield 3.4.10 → 3.4.11
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.
- package/README.md +80 -207
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -9,6 +9,29 @@
|
|
|
9
9
|
|
|
10
10
|
▶️ **[Watch: SpecShield in 60 seconds](https://www.youtube.com/watch?v=7Tp502KN5R8)**
|
|
11
11
|
|
|
12
|
+
> **Contract Compatibility Testing · OpenAPI Diff · Breaking-Change Detection · `can-i-deploy` Deploy Gate · API Governance & Linting · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
|
|
13
|
+
|
|
14
|
+
## Never ship a breaking change to your API consumers
|
|
15
|
+
|
|
16
|
+
**SpecShield™ is contract compatibility testing for APIs** — catch breaking changes before they reach your consumers, and gate every deploy with `can-i-deploy`. *(Contract compatibility testing is also known as bidirectional contract testing.)*
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install -g specshield
|
|
20
|
+
specshield compare base.yaml target.yaml --fail-on-breaking
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
No account, no config, no broker to run or host. Language-agnostic. Local mode never uploads your specs.
|
|
24
|
+
|
|
25
|
+
What the CLI does:
|
|
26
|
+
|
|
27
|
+
1. **Diff** two OpenAPI specs and fail CI on breaking changes. *(Free)*
|
|
28
|
+
2. **Contract compatibility testing** with `can-i-deploy` — block a deploy that would break a consumer. *(Team)*
|
|
29
|
+
3. **`govern`** — lint your spec against OWASP + design rules and gate the PR on violations. *(Team)*
|
|
30
|
+
4. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL). *(Free)*
|
|
31
|
+
5. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec. *(Free)*
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
12
35
|
## Contents
|
|
13
36
|
|
|
14
37
|
**Get started**
|
|
@@ -16,7 +39,7 @@
|
|
|
16
39
|
|
|
17
40
|
**Why SpecShield**
|
|
18
41
|
- [The Problem](#the-problem) · [The Solution](#the-solution) · [See It in Action](#see-it-in-action) · [Use Cases](#use-cases)
|
|
19
|
-
- [
|
|
42
|
+
- [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
|
|
20
43
|
|
|
21
44
|
**Commands — local & hosted compare**
|
|
22
45
|
- [Local Compare](#local-compare) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
|
|
@@ -25,7 +48,7 @@
|
|
|
25
48
|
- [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr)
|
|
26
49
|
|
|
27
50
|
**Contract Compatibility Testing — the `bdct` commands**
|
|
28
|
-
- [Overview & full command reference](#
|
|
51
|
+
- [Overview & full command reference](#contract-compatibility-testing--the-bdct-commands)
|
|
29
52
|
- [`bdct capture from-har` — HAR → consumer contract](#bdct-capture-from-har--turn-real-traffic-into-a-consumer-contract)
|
|
30
53
|
- [Step 1 — record a HAR](#step-1--record-a-har-file) · [Step 2 — generate contract](#step-2--turn-the-har-into-a-consumer-contract) · [Step 3 — publish + gate](#step-3--publish--gate) · [Operational concerns](#operational-concerns-read-this-before-going-live)
|
|
31
54
|
- [`bdct verify-provider` — spec-vs-production conformance](#bdct-verify-provider--does-your-live-provider-actually-match-its-spec)
|
|
@@ -41,38 +64,14 @@
|
|
|
41
64
|
|
|
42
65
|
---
|
|
43
66
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
## Never ship a breaking change to your API consumers
|
|
49
|
-
|
|
50
|
-
**SpecShield™ is contract compatibility testing for APIs** — catch breaking changes before they reach your consumers, and gate every deploy with `can-i-deploy`. *(Contract compatibility testing is also known as bidirectional contract testing.)*
|
|
51
|
-
|
|
52
|
-
It's the one CLI that does five things to keep your API safe:
|
|
53
|
-
|
|
54
|
-
1. **Diff** two OpenAPI specs and fail CI on breaking changes.
|
|
55
|
-
2. **Contract compatibility testing** with `can-i-deploy` — block a deploy that would break a consumer.
|
|
56
|
-
3. **`govern`** — lint your spec against OWASP + design rules and gate the PR on violations.
|
|
57
|
-
4. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL).
|
|
58
|
-
5. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec.
|
|
59
|
-
|
|
60
|
-
```
|
|
61
|
-
OpenAPI diff + contract compatibility checks + API governance + HAR → consumer contract + spec-vs-production conformance — in one CLI.
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
No broker. No Pact DSL. Language-agnostic. Works in 30 seconds. Local mode never uploads your specs.
|
|
65
|
-
|
|
66
|
-
---
|
|
67
|
-
|
|
68
|
-
## One platform, five ways to run it
|
|
67
|
+
## Where it runs
|
|
69
68
|
|
|
70
69
|
This CLI is one surface of the **SpecShield™ platform**. The same contract-compatibility and governance engine powers every entry point — they share one project file (`.specshield.yml`), one API key, and one set of audit events. Adopt the one that fits your stack today and grow into the others:
|
|
71
70
|
|
|
72
71
|
| Surface | Best for |
|
|
73
72
|
|---|---|
|
|
74
73
|
| **GitHub App** — [github.com/apps/specshield-deploy-gate](https://github.com/apps/specshield-deploy-gate) | Zero-config PR checks. Install once; every PR gets a check run and a diff comment. |
|
|
75
|
-
| **GitHub Action** — [`specshield-io/bdct-action@v1`](https://github.com/marketplace/actions/specshield-bdct) | Pinned, reproducible
|
|
74
|
+
| **GitHub Action** — [`specshield-io/bdct-action@v1`](https://github.com/marketplace/actions/specshield-bdct) | Pinned, reproducible contract-compatibility + governance gate in any GitHub workflow. |
|
|
76
75
|
| **CLI** *(this package)* | Any CI — GitLab, Jenkins, CircleCI, Bitbucket, Drone — or your laptop. |
|
|
77
76
|
| **IntelliJ plugin** — [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/33137-specshield) | Inline spec findings, one-click auto-fixes, compare & explain — inside IntelliJ IDEA, WebStorm, PyCharm and more. |
|
|
78
77
|
| **MCP server** — [`specshield-mcp-server`](https://github.com/specshield-io/specshield-mcp-server) | Give Claude, Cursor, and other AI agents the same deploy gate. |
|
|
@@ -94,6 +93,8 @@ Plus a hosted **dashboard** at [specshield.io](https://specshield.io) — compat
|
|
|
94
93
|
- A required field changes — partner integrations fail at 2am.
|
|
95
94
|
- You find out from an angry customer, not from CI.
|
|
96
95
|
|
|
96
|
+
It's rarely guarded against: in [our survey of public repos that publish OpenAPI specs](https://specshield.io/blog/95-percent-no-compatibility-gate), **95% had no breaking-change check in CI at all.**
|
|
97
|
+
|
|
97
98
|
Manual review doesn't catch it. Integration tests run too late.
|
|
98
99
|
**You need a contract between your services — and something that enforces it on every PR and every deploy.**
|
|
99
100
|
|
|
@@ -171,9 +172,9 @@ npm install -g specshield
|
|
|
171
172
|
specshield compare base.yaml target.yaml --fail-on-breaking
|
|
172
173
|
```
|
|
173
174
|
|
|
174
|
-
Works with
|
|
175
|
+
Works with OpenAPI 3.0 / 3.1 and Swagger 2.0, in YAML or JSON.
|
|
175
176
|
|
|
176
|
-
**For
|
|
177
|
+
**For the `bdct` commands**, run the wizard once and never re-type the same flags again:
|
|
177
178
|
|
|
178
179
|
```bash
|
|
179
180
|
specshield init
|
|
@@ -190,7 +191,9 @@ specshield bdct can-i-deploy --version $GITHUB_SHA
|
|
|
190
191
|
|
|
191
192
|
---
|
|
192
193
|
|
|
193
|
-
##
|
|
194
|
+
## Example: how it plays out
|
|
195
|
+
|
|
196
|
+
*An illustrative scenario:*
|
|
194
197
|
|
|
195
198
|
> The `payment-service` team merged a change that renamed `status` to
|
|
196
199
|
> `paymentStatus`. The `checkout-ui` team wasn't notified.
|
|
@@ -224,30 +227,6 @@ specshield bdct can-i-deploy --version $GITHUB_SHA
|
|
|
224
227
|
|
|
225
228
|
---
|
|
226
229
|
|
|
227
|
-
## Local vs Cloud
|
|
228
|
-
|
|
229
|
-
| Feature | Local (Free) | Team | Enterprise |
|
|
230
|
-
|---|---|---|---|
|
|
231
|
-
| Compare two spec files | ✅ | ✅ | ✅ |
|
|
232
|
-
| Breaking change detection | ✅ | ✅ | ✅ |
|
|
233
|
-
| JSON / human output | ✅ | ✅ | ✅ |
|
|
234
|
-
| Fail CI on breaking change | ✅ | ✅ | ✅ |
|
|
235
|
-
| **`bdct capture from-har`** | ✅ | ✅ | ✅ |
|
|
236
|
-
| **`bdct verify-provider`** | ✅ | ✅ | ✅ |
|
|
237
|
-
| `specshield history` — compare timeline | ❌ | ✅ | ✅ |
|
|
238
|
-
| `specshield share` — public report URLs | ❌ | ✅ | ✅ |
|
|
239
|
-
| Hosted dashboard | ❌ | ✅ | ✅ |
|
|
240
|
-
| GitHub App PR checks | ❌ | ✅ | ✅ |
|
|
241
|
-
| BDCT consumer registry + can-i-deploy gate | ❌ | ✅ | ✅ |
|
|
242
|
-
| BDCT compatibility matrix | ❌ | ✅ | ✅ |
|
|
243
|
-
| Team workspace + audit log + RBAC | ❌ | ✅ | ✅ |
|
|
244
|
-
| Slack notifications | ❌ | ✅ | ✅ |
|
|
245
|
-
| SAML SSO, SCIM, on-prem | ❌ | ❌ | ✅ |
|
|
246
|
-
|
|
247
|
-
> **The local-only commands are first-class.** `compare`, `bdct capture from-har`, and `bdct verify-provider` all run entirely in your CI — your spec text never leaves your infrastructure.
|
|
248
|
-
|
|
249
|
-
---
|
|
250
|
-
|
|
251
230
|
# Commands
|
|
252
231
|
|
|
253
232
|
## Local Compare
|
|
@@ -275,7 +254,8 @@ specshield compare base.yaml target.yaml --ignore "DELETE /admin removed" --fail
|
|
|
275
254
|
|
|
276
255
|
Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
|
|
277
256
|
heavy comparison off your CI runner and for cross-validating against the
|
|
278
|
-
exact engine the dashboard uses. Requires a free account
|
|
257
|
+
exact engine the dashboard uses. Requires an API key from a free account —
|
|
258
|
+
without one the CLI exits with code `2` (`No API key found`).
|
|
279
259
|
|
|
280
260
|
```bash
|
|
281
261
|
specshield compare base.yaml target.yaml --remote
|
|
@@ -283,10 +263,9 @@ specshield compare base.yaml target.yaml --remote --fail-on-breaking
|
|
|
283
263
|
specshield compare base.yaml target.yaml --remote --json --output result.json
|
|
284
264
|
```
|
|
285
265
|
|
|
286
|
-
> **History note:**
|
|
287
|
-
>
|
|
288
|
-
>
|
|
289
|
-
> `specshield share`. Without a key the diff still runs — it just isn't saved.
|
|
266
|
+
> **History note:** set your key with `specshield login`, `--api-key`, or
|
|
267
|
+
> `SPECSHIELD_API_KEY`. Each `--remote` comparison is saved to your history,
|
|
268
|
+
> and the response includes a `historyId` you can hand to `specshield share`.
|
|
290
269
|
|
|
291
270
|
## Comparison History
|
|
292
271
|
|
|
@@ -427,13 +406,15 @@ Run it in CI right after your build:
|
|
|
427
406
|
|
|
428
407
|
---
|
|
429
408
|
|
|
430
|
-
#
|
|
409
|
+
# Contract Compatibility Testing — the `bdct` commands
|
|
431
410
|
|
|
432
411
|
**Compatibility without Pact's broker overhead or DSL.**
|
|
433
412
|
|
|
413
|
+
> **Plan:** the registry commands — `publish-provider`, `publish-consumer`, `verify`, `can-i-deploy`, `matrix` and the `list*` commands — need a **Team** plan — on Free the server rejects them with a paid-plan error (exit code `2`). `capture from-har` and `verify-provider` are free and run fully locally. **[See plans →](https://specshield.io/pricing)**
|
|
414
|
+
|
|
434
415
|
Both sides publish what they have — provider publishes its OpenAPI spec, consumer publishes either an OpenAPI subset *or* a Pact JSON file — and SpecShield's engine verifies that every endpoint/field the consumer relies on is satisfied by the provider. `can-i-deploy` then gates the deploy.
|
|
435
416
|
|
|
436
|
-
### How
|
|
417
|
+
### How it works
|
|
437
418
|
|
|
438
419
|
1. Consumer publishes a contract (OpenAPI subset *or* Pact JSON).
|
|
439
420
|
2. Provider publishes its full OpenAPI spec.
|
|
@@ -584,7 +565,7 @@ specshield bdct list-consumers --org acme-store --consumer checkout-ui
|
|
|
584
565
|
specshield bdct list --org acme-store --provider payment-service --env production
|
|
585
566
|
```
|
|
586
567
|
|
|
587
|
-
### Full
|
|
568
|
+
### Full workflow
|
|
588
569
|
|
|
589
570
|
```bash
|
|
590
571
|
# 1. Provider publishes spec on every release
|
|
@@ -604,9 +585,9 @@ specshield bdct can-i-deploy \
|
|
|
604
585
|
--version v2.1.0 --env production
|
|
605
586
|
```
|
|
606
587
|
|
|
607
|
-
###
|
|
588
|
+
### JSON output
|
|
608
589
|
|
|
609
|
-
All
|
|
590
|
+
All `bdct` commands support `--json` for CI parsing:
|
|
610
591
|
|
|
611
592
|
```bash
|
|
612
593
|
specshield bdct can-i-deploy --org acme-store --service payment-service --version v2.1.0 --json
|
|
@@ -630,7 +611,7 @@ specshield bdct can-i-deploy --org acme-store --service payment-service --versio
|
|
|
630
611
|
|
|
631
612
|
# `bdct capture from-har` — turn real traffic into a consumer contract
|
|
632
613
|
|
|
633
|
-
**This is the feature that makes
|
|
614
|
+
**This is the feature that makes contract testing actually work for normal teams.**
|
|
634
615
|
Pact requires every consumer team to learn a DSL, instrument their tests,
|
|
635
616
|
and run a broker. SpecShield asks for something they already have: a
|
|
636
617
|
recording of an HTTP test run, in the universal HAR format that every
|
|
@@ -658,7 +639,7 @@ integration" and "we proved the integration."
|
|
|
658
639
|
```
|
|
659
640
|
|
|
660
641
|
Step 1 already happens in your team — you're just saving the file. Step 2
|
|
661
|
-
is one CLI command. Step 3 is the
|
|
642
|
+
is one CLI command. Step 3 is the contract registry you publish to.
|
|
662
643
|
|
|
663
644
|
---
|
|
664
645
|
|
|
@@ -676,118 +657,10 @@ project. You almost never have to write recorder code yourself.
|
|
|
676
657
|
| **[Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting/exporting-postman-data/#exporting-as-har)** / Insomnia / Bruno | Manually exercised during exploratory testing | Right-click → export |
|
|
677
658
|
| **[k6](https://grafana.com/docs/k6/latest/results-output/real-time/json/#har)** load tests | Already running k6 against the provider | One `--out har=…` flag |
|
|
678
659
|
|
|
679
|
-
**
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
1. Open the page that calls your API in the browser.
|
|
685
|
-
2. Open DevTools (`F12` / `Cmd+Opt+I`) → **Network** tab.
|
|
686
|
-
3. Click the 🚫 button to clear, then reload the page and click through the
|
|
687
|
-
flows you want to record.
|
|
688
|
-
4. Right-click anywhere in the request list → **Save all as HAR with
|
|
689
|
-
content** → save as `traffic.har`.
|
|
690
|
-
|
|
691
|
-
That's the entire recording. The file is byte-compatible with everything
|
|
692
|
-
SpecShield does.
|
|
693
|
-
|
|
694
|
-
> **Safari note:** Safari's "Export HAR" is under the Develop menu →
|
|
695
|
-
> *Export…* in the Network tab; it produces the same format.
|
|
696
|
-
|
|
697
|
-
### 1b. Playwright (best for teams with UI tests)
|
|
698
|
-
|
|
699
|
-
Add one option to your `playwright.config.js`:
|
|
700
|
-
|
|
701
|
-
```js
|
|
702
|
-
// playwright.config.js
|
|
703
|
-
const path = require('path');
|
|
704
|
-
module.exports = {
|
|
705
|
-
testDir: './tests',
|
|
706
|
-
use: {
|
|
707
|
-
baseURL: 'https://staging.acme.com',
|
|
708
|
-
recordHar: { path: path.resolve(__dirname, 'traffic.har'), mode: 'full', content: 'embed' },
|
|
709
|
-
},
|
|
710
|
-
};
|
|
711
|
-
```
|
|
712
|
-
|
|
713
|
-
Run your tests as usual:
|
|
714
|
-
|
|
715
|
-
```bash
|
|
716
|
-
npx playwright test
|
|
717
|
-
# → writes traffic.har on context close
|
|
718
|
-
```
|
|
719
|
-
|
|
720
|
-
The HAR will contain every HTTP call the browser made during the test —
|
|
721
|
-
HTML, JS, images, and the API JSON. The `--onlyJson` default in Step 2
|
|
722
|
-
filters out the noise automatically.
|
|
723
|
-
|
|
724
|
-
> Need the HAR file flushed **per test**? Create the context explicitly in
|
|
725
|
-
> your test and call `await context.close()` at the end. A runnable
|
|
726
|
-
> copy-paste starter lives in [`examples/playwright-har/`](examples/playwright-har/)
|
|
727
|
-
> of this repo — clone, `npm install`, `npx playwright install chromium`,
|
|
728
|
-
> `npm test` produces `traffic.har` against the public JSONPlaceholder
|
|
729
|
-
> sandbox so you can verify the toolchain works before pointing it at your
|
|
730
|
-
> own provider.
|
|
731
|
-
|
|
732
|
-
### 1c. Cypress
|
|
733
|
-
|
|
734
|
-
```bash
|
|
735
|
-
npm i -D @neuralegion/cypress-har-generator
|
|
736
|
-
```
|
|
737
|
-
|
|
738
|
-
```js
|
|
739
|
-
// cypress.config.js
|
|
740
|
-
const { install } = require('@neuralegion/cypress-har-generator');
|
|
741
|
-
module.exports = { e2e: { setupNodeEvents(on, config) { install(on); return config; } } };
|
|
742
|
-
|
|
743
|
-
// cypress/support/e2e.js
|
|
744
|
-
beforeEach(() => cy.recordHar());
|
|
745
|
-
afterEach(() => cy.saveHar({ outDir: './har-out' }));
|
|
746
|
-
```
|
|
747
|
-
|
|
748
|
-
Run `npx cypress run` and the HAR for each spec lands in `har-out/`.
|
|
749
|
-
|
|
750
|
-
### 1d. mitmproxy (best for backend service-to-service)
|
|
751
|
-
|
|
752
|
-
When the consumer is a backend service (no browser), point it through
|
|
753
|
-
mitmproxy in your integration-test env. No consumer code change.
|
|
754
|
-
|
|
755
|
-
```bash
|
|
756
|
-
# Install once
|
|
757
|
-
brew install mitmproxy # macOS — also available via pip and apt
|
|
758
|
-
|
|
759
|
-
# Start the proxy and tell it to dump HAR
|
|
760
|
-
mitmdump --set hardump=traffic.har --listen-port 8080
|
|
761
|
-
|
|
762
|
-
# In another terminal: run your tests with HTTPS_PROXY pointing at it
|
|
763
|
-
HTTPS_PROXY=http://localhost:8080 HTTP_PROXY=http://localhost:8080 \
|
|
764
|
-
./run-integration-tests.sh
|
|
765
|
-
|
|
766
|
-
# Ctrl-C mitmdump when done — traffic.har is on disk
|
|
767
|
-
```
|
|
768
|
-
|
|
769
|
-
The `hardump` add-on is built into mitmproxy ≥ 9.0. For TLS hosts you'll
|
|
770
|
-
need to trust mitmproxy's CA in your test JVM/runtime (see the
|
|
771
|
-
[mitmproxy CA docs](https://docs.mitmproxy.org/stable/concepts-certificates/));
|
|
772
|
-
in many test environments it's a single env var
|
|
773
|
-
(`NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, or a
|
|
774
|
-
JVM `cacerts` import).
|
|
775
|
-
|
|
776
|
-
### 1e. Postman / Insomnia / Bruno
|
|
777
|
-
|
|
778
|
-
Run the request (or a whole collection runner). Right-click the response
|
|
779
|
-
→ **Save Response as HAR**. Repeat for each request you want included,
|
|
780
|
-
then either keep them as separate `.har` files (pass `--in` once per file
|
|
781
|
-
via a loop in CI) or merge them with any HAR-merge tool.
|
|
782
|
-
|
|
783
|
-
### 1f. k6 load test (bonus — recording while load-testing)
|
|
784
|
-
|
|
785
|
-
```bash
|
|
786
|
-
k6 run --out har=traffic.har script.js
|
|
787
|
-
```
|
|
788
|
-
|
|
789
|
-
k6 emits a HAR alongside its load metrics. Same file works with
|
|
790
|
-
`bdct capture from-har`.
|
|
660
|
+
**Step-by-step recipes for each recorder** (DevTools, Playwright, Cypress,
|
|
661
|
+
mitmproxy, Postman, k6) are in
|
|
662
|
+
[`docs/har-recipes.md`](https://github.com/specshield-io/specshield-cli/blob/main/docs/har-recipes.md).
|
|
663
|
+
The Step 2 command is identical whichever recorder you use.
|
|
791
664
|
|
|
792
665
|
---
|
|
793
666
|
|
|
@@ -869,7 +742,7 @@ specshield bdct can-i-deploy \
|
|
|
869
742
|
# exit 0 = safe; exit 1 = a verification says NO and the deploy is blocked
|
|
870
743
|
```
|
|
871
744
|
|
|
872
|
-
Full
|
|
745
|
+
Full command reference is in the [Contract Compatibility Testing](#contract-compatibility-testing--the-bdct-commands)
|
|
873
746
|
section above.
|
|
874
747
|
|
|
875
748
|
---
|
|
@@ -971,26 +844,11 @@ syntax changes.
|
|
|
971
844
|
|
|
972
845
|
---
|
|
973
846
|
|
|
974
|
-
## Why this is the most valuable piece of the CLI
|
|
975
|
-
|
|
976
|
-
Every other contract-testing product on the market asks the consumer team
|
|
977
|
-
to **change their code** — adopt a DSL, instrument their tests, run a
|
|
978
|
-
broker. That tax is why most teams that "should" be doing contract testing
|
|
979
|
-
aren't.
|
|
980
|
-
|
|
981
|
-
`bdct capture from-har` removes the tax. Your team's existing test run is
|
|
982
|
-
already the contract; the CLI just converts the format. The HAR-capture →
|
|
983
|
-
publish → can-i-deploy loop is what turns "we have OpenAPI specs in a
|
|
984
|
-
folder" into "no provider PR merges if it would break a deployed consumer"
|
|
985
|
-
— with measurable enforcement, in one CI step, and no per-language SDK.
|
|
986
|
-
|
|
987
|
-
---
|
|
988
|
-
|
|
989
847
|
# `bdct verify-provider` — does your live provider actually match its spec?
|
|
990
848
|
|
|
991
849
|
**Active spec-vs-production conformance — Dredd-style, in CI.**
|
|
992
850
|
|
|
993
|
-
Most teams trust the provider's OpenAPI as the source of truth and never check whether the running service actually matches it. SpecShield's compatibility engine
|
|
851
|
+
Most teams trust the provider's OpenAPI as the source of truth and never check whether the running service actually matches it. SpecShield's compatibility engine is only as accurate as that trust — so `verify-provider` closes the loop by **firing probes derived from the spec at a running endpoint** (staging, usually) and validating every response body against the spec's schema for its status code.
|
|
994
852
|
|
|
995
853
|
Catches things like: the spec says `status ∈ {paid, pending, refunded}` but the live API sometimes returns `partially_refunded`. Or a field documented as `required` is sometimes missing. Or a `format: uuid` field actually contains a numeric ID.
|
|
996
854
|
|
|
@@ -1105,7 +963,7 @@ jobs:
|
|
|
1105
963
|
### On Push — Publish provider spec + gate the deploy
|
|
1106
964
|
|
|
1107
965
|
```yaml
|
|
1108
|
-
name:
|
|
966
|
+
name: Publish Provider & Deploy Gate
|
|
1109
967
|
on:
|
|
1110
968
|
push:
|
|
1111
969
|
branches: [main]
|
|
@@ -1170,7 +1028,7 @@ jobs:
|
|
|
1170
1028
|
| | **SpecShield** | **Pact / PactFlow** (SmartBear) | **oasdiff** | **Specmatic** / **Microcks** (OSS) |
|
|
1171
1029
|
|---|---|---|---|---|
|
|
1172
1030
|
| OpenAPI-native | ✅ | partial (Pact DSL) | ✅ | ✅ |
|
|
1173
|
-
| No broker
|
|
1031
|
+
| No broker to run or host | ✅ | ❌ (Pact Broker or paid PactFlow) | ✅ | ✅ |
|
|
1174
1032
|
| Bi-directional contract testing | ✅ | ✅ (Pactflow paid) | ❌ | partial |
|
|
1175
1033
|
| Breaking-change detection | ✅ | ❌ | ✅ | ❌ |
|
|
1176
1034
|
| `can-i-deploy` gating | ✅ | ✅ (broker) | ❌ | ❌ |
|
|
@@ -1191,10 +1049,13 @@ jobs:
|
|
|
1191
1049
|
| Plan | Price | What's included |
|
|
1192
1050
|
|---|---|---|
|
|
1193
1051
|
| **Free** | $0 forever | Local compare · `bdct capture from-har` · `bdct verify-provider` · public web diff · 7-day compare history · 1 GitHub App PR check |
|
|
1194
|
-
| **Team** | $89/mo ($75
|
|
1195
|
-
| **Enterprise** |
|
|
1052
|
+
| **Team** | $89/mo, or $900/yr ($75/mo) · up to 10 users | Everything in Free + consumer registry · enforced `can-i-deploy` gate · compatibility matrix · `govern` governance gate · audit trail · Slack alerts · team workspace + RBAC · priority email support |
|
|
1053
|
+
| **Enterprise** | Custom · unlimited users | Everything in Team + SSO and on-prem / private-cloud (on request) · advanced RBAC + audit-log export · dedicated onboarding + SLA |
|
|
1196
1054
|
|
|
1197
|
-
|
|
1055
|
+
Prices exclude VAT/GST, added at checkout where applicable. No credit card for the free plan.
|
|
1056
|
+
|
|
1057
|
+
> **The local-only commands are first-class.** `compare`, `bdct capture from-har`, and `bdct verify-provider` run entirely in your CI on the Free plan — your spec text never leaves your infrastructure.
|
|
1058
|
+
**[Get started free →](https://specshield.io)** · For Enterprise: [sales@specshield.io](mailto:sales@specshield.io).
|
|
1198
1059
|
|
|
1199
1060
|
---
|
|
1200
1061
|
|
|
@@ -1206,7 +1067,7 @@ Run once at the root of your project. The wizard:
|
|
|
1206
1067
|
2. Detects your service name (`package.json`, `pyproject.toml`, `pom.xml`, `go.mod`, `Cargo.toml`, or directory name).
|
|
1207
1068
|
3. Detects your git branch and suggests `production` for `main`/`master`, `staging` otherwise.
|
|
1208
1069
|
4. Asks whether this project is a provider, a consumer, or both.
|
|
1209
|
-
5. Asks for your org key
|
|
1070
|
+
5. Asks for your org key — copy it from the dashboard at [specshield.io/account/team](https://specshield.io/account/team).
|
|
1210
1071
|
6. Validates / stores your API key.
|
|
1211
1072
|
7. Writes **`.specshield.yml`** and (optionally) a starter **`.github/workflows/specshield-bdct.yml`** using [`specshield-io/bdct-action@v1`](https://github.com/marketplace/actions/specshield-bdct).
|
|
1212
1073
|
|
|
@@ -1278,7 +1139,7 @@ specshield init --no-interactive \
|
|
|
1278
1139
|
| `--consumer-provider <name>` | The provider this consumer talks to. |
|
|
1279
1140
|
| `--contract <path>` | Path to the consumer contract (OpenAPI or Pact JSON). |
|
|
1280
1141
|
| `--format <fmt>` | Consumer contract format: `OPENAPI` (default) or `PACT`. |
|
|
1281
|
-
| `--env <environment>` | Default environment for
|
|
1142
|
+
| `--env <environment>` | Default environment for `bdct` operations. |
|
|
1282
1143
|
| `--write-workflow` | Also write a starter GitHub Actions workflow. |
|
|
1283
1144
|
|
|
1284
1145
|
> **What is _not_ written into `.specshield.yml`:** your API key. It's stored in `~/.specshield/config.json` (set by `specshield login`) or read from `SPECSHIELD_API_KEY` in CI. The project file is committed; never commit a secret into it.
|
|
@@ -1346,7 +1207,7 @@ remote:
|
|
|
1346
1207
|
url: https://specshield.io/compare
|
|
1347
1208
|
timeout: 10000
|
|
1348
1209
|
|
|
1349
|
-
#
|
|
1210
|
+
# `bdct` defaults (used by every `specshield bdct …` subcommand).
|
|
1350
1211
|
bdct:
|
|
1351
1212
|
org: acme-pay
|
|
1352
1213
|
environment: staging
|
|
@@ -1370,7 +1231,7 @@ github:
|
|
|
1370
1231
|
commentOnPr: true
|
|
1371
1232
|
```
|
|
1372
1233
|
|
|
1373
|
-
With this file,
|
|
1234
|
+
With this file, `bdct` commands collapse to `--version`:
|
|
1374
1235
|
|
|
1375
1236
|
```bash
|
|
1376
1237
|
specshield bdct publish-provider --version $GITHUB_SHA
|
|
@@ -1394,9 +1255,10 @@ specshield compare <base> <target> [options]
|
|
|
1394
1255
|
| `--json` | Machine-readable JSON output |
|
|
1395
1256
|
| `--output <file>` | Save result to file |
|
|
1396
1257
|
| `--ignore <change>` | Ignore a specific change (repeatable) |
|
|
1397
|
-
| `--severity <level>` | `info` / `warning` / `error` |
|
|
1258
|
+
| `--severity <level>` | Minimum severity shown: `info` / `warning` / `error` (default `info`) |
|
|
1398
1259
|
| `--config <path>` | Path to `.specshield.yml` |
|
|
1399
|
-
| `--
|
|
1260
|
+
| `--remote-url <url>` | Override the hosted API base URL |
|
|
1261
|
+
| `--timeout <ms>` | Request timeout for remote mode (default `10000`) |
|
|
1400
1262
|
|
|
1401
1263
|
```bash
|
|
1402
1264
|
specshield history [options]
|
|
@@ -1417,6 +1279,17 @@ specshield share <reportId | base.yaml target.yaml> [options]
|
|
|
1417
1279
|
| `--expires <days>` | Make the link expire after N days (default: never) |
|
|
1418
1280
|
| `--api-key <key>` | Override stored API key |
|
|
1419
1281
|
|
|
1282
|
+
```bash
|
|
1283
|
+
specshield whoami [options] # show the signed-in account
|
|
1284
|
+
specshield logout # remove the stored API key
|
|
1285
|
+
```
|
|
1286
|
+
|
|
1287
|
+
| Option (`whoami`) | Description |
|
|
1288
|
+
|---|---|
|
|
1289
|
+
| `--api-token <key>` | Override stored / env API token for this call |
|
|
1290
|
+
| `--server <url>` | Override SpecShield server URL |
|
|
1291
|
+
| `--json` | Machine-readable JSON output |
|
|
1292
|
+
|
|
1420
1293
|
```bash
|
|
1421
1294
|
specshield govern <spec> [options]
|
|
1422
1295
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specshield",
|
|
3
|
-
"version": "3.4.
|
|
3
|
+
"version": "3.4.11",
|
|
4
4
|
"description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
|
|
5
5
|
"main": "src/cli.js",
|
|
6
6
|
"homepage": "https://specshield.io",
|