@ksz54213/specbridge 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# SpecBridge
+
+> Contract testing CLI — verify HTTP APIs against Gherkin feature files.
+
+SpecBridge lets you describe the expected behaviour of an HTTP API in plain-English Gherkin (`.feature`) files and then verify a live service against those contracts from the command line.
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+
+---
+
+## Installation
+
+```bash
+npm install -g @ksz54213/specbridge
+```
+
+---
+
+## Usage
+
+```
+specbridge verify -f <path-to-feature> -u <base-url>
+```
+
+| Option | Alias | Required | Description |
+|---|---|---|---|
+| `--file` | `-f` | ✅ | Path to the `.feature` contract file |
+| `--url` | `-u` | ✅ | Base URL of the service to test (e.g. `http://localhost:3000`) |
+
+---
+
+## Writing a Contract
+
+Contracts are written in [Gherkin](https://cucumber.io/docs/gherkin/) and stored as `.feature` files.
+Each **Scenario** maps to one API call and a set of assertions.
+
+### Supported Steps
+
+| Step | Description |
+|---|---|
+| `When I send a "METHOD" request to "/path"` | HTTP request (GET, POST, PUT, DELETE, …) |
+| `And the request body is:` + doc-string | JSON request body |
+| `Then the response status should be <code>` | Assert HTTP status code |
+| `Then the response body should be:` + doc-string | Assert exact JSON response (key-by-key) |
+| `Then the response body should contain field "key" with value "val"` | Assert a single field value |
+
+> A scenario **must** include at least one `When` step and one `Then` status step to be executed.
+> Scenarios missing these are skipped with a warning.
+
+---
+
+## End-to-End Example
+
+The `example-api/` directory contains a small Node.js server and `example.feature` provides its contract.
+
+### 1 — Start the example API
+
+```bash
+cd example-api
+npm start
+# Example API running at http://localhost:3000
+```
+
+### 2 — Run contract verification
+
+From the project root:
+
+```bash
+specbridge verify -f example.feature -u http://localhost:3000
+```
+
+### 3 — Expected output
+
+```
+✅  Scenario: Health check endpoint
+    GET http://localhost:3000/api/health
+✅  Scenario: Get user by ID
+    GET http://localhost:3000/api/users/1
+✅  Scenario: Create a new user
+    POST http://localhost:3000/api/users
+────────────────────────────────
+  Results: 3 passed, 0 failed
+────────────────────────────────
+```
+
+### The contract file (`example.feature`)
+
+```gherkin
+Feature: API Contract Verification
+
+  Scenario: Health check endpoint
+    When I send a "GET" request to "/api/health"
+    Then the response status should be 200
+    Then the response body should contain field "status" with value "ok"
+
+  Scenario: Get user by ID
+    When I send a "GET" request to "/api/users/1"
+    Then the response status should be 200
+    Then the response body should be:
+      """
+      { "id": 1, "name": "John" }
+      """
+
+  Scenario: Create a new user
+    When I send a "POST" request to "/api/users"
+    And the request body is:
+      """
+      { "name": "Alice", "email": "alice@example.com" }
+      """
+    Then the response status should be 201
+    Then the response body should contain field "name" with value "Alice"
+```
+
+### The example API endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/api/health` | Health check — returns `{ "status": "ok" }` |
+| `GET` | `/api/users/:id` | Fetch a user by ID |
+| `POST` | `/api/users` | Create a new user (requires `name` in body) |
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | All scenarios passed |
+| `1` | One or more scenarios failed, or the feature file was not found / could not be parsed |
+
+---
+
+## Running Tests
+
+```bash
+npm test
+```
+
+---
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { program } from 'commander'
+import { existsSync } from 'node:fs'
+import { parseFeatureFile } from './src/parser.js'
+import { buildEndpoint } from './src/endpoint.js'
+import { runScenario } from './src/runner.js'
+import { reportScenario, reportSkipped, reportSummary } from './src/reporter.js'
+
+program
+  .name('specbridge')
+  .description('Contract testing CLI — verify HTTP APIs against Gherkin feature files')
+  .version('0.1.0')
+
+program
+  .command('verify')
+  .description('Verify a contract defined in a Gherkin feature file')
+  .requiredOption('-f, --file <path>', 'Path to the .feature file')
+  .requiredOption('-u, --url <url>', 'Base URL of the service to test')
+  .action(async (opts) => {
+    if (!existsSync(opts.file)) {
+      console.error(`\x1b[31mError: Feature File not found: ${opts.file}\x1b[0m`)
+      process.exit(1)
+    }
+
+    let scenarios
+    try {
+      scenarios = await parseFeatureFile(opts.file)
+    } catch (err) {
+      console.error(`\x1b[31mError: Failed to parse feature file: ${err.message}\x1b[0m`)
+      process.exit(1)
+    }
+
+    if (scenarios.length === 0) {
+      console.log('\x1b[33mNo scenarios found in feature file\x1b[0m')
+      process.exit(0)
+    }
+
+    let passed = 0
+    let failed = 0
+
+    for (const scenario of scenarios) {
+      if (!scenario.method || scenario.expectedStatus === null) {
+        reportSkipped(scenario.name)
+        continue
+      }
+
+      const endpoint = buildEndpoint(opts.url, scenario.path)
+      const result = await runScenario(scenario, opts.url)
+      reportScenario(scenario.name, endpoint, result)
+
+      if (result.pass) passed++
+      else failed++
+    }
+
+    reportSummary(passed, failed)
+    process.exit(failed > 0 ? 1 : 0)
+  })
+
+program.parse()

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ksz54213/specbridge",
+  "version": "0.1.0",
+  "description": "Contract testing CLI tool — verify HTTP APIs against Gherkin feature files",
+  "type": "module",
+  "bin": {
+    "specbridge": "index.js"
+  },
+  "files": [
+    "src",
+    "index.js"
+  ],
+  "scripts": {
+    "test": "node --test --test-reporter=spec",
+    "test:watch": "node --test --watch"
+  },
+  "keywords": [
+    "contract-testing",
+    "gherkin",
+    "api",
+    "cli",
+    "bdd"
+  ],
+  "author": "James Hsueh",
+  "license": "MIT",
+  "dependencies": {
+    "@cucumber/gherkin": "^29.0.0",
+    "@cucumber/messages": "^26.0.0",
+    "axios": "^1.7.0",
+    "chai": "^5.0.0",
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "nock": "^13.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/assertions.js

@@ -0,0 +1,30 @@
+export function assertStatusCode(actual, expected) {
+  if (actual === expected) return { pass: true }
+  return { pass: false, message: `Status Code: expected ${expected}, got ${actual}` }
+}
+
+export function assertBodyExact(actual, expected) {
+  try {
+    for (const [key, val] of Object.entries(expected)) {
+      const actualVal = actual[key]
+      if (JSON.stringify(actualVal) !== JSON.stringify(val)) {
+        return {
+          pass: false,
+          message: `Response Body mismatch: expected field "${key}" to equal ${JSON.stringify(val)}, got ${JSON.stringify(actualVal)}`
+        }
+      }
+    }
+    return { pass: true }
+  } catch (err) {
+    return { pass: false, message: `Response Body assertion error: ${err.message}` }
+  }
+}
+
+export function assertBodyField(actual, field, value) {
+  const actualVal = String(actual[field] ?? '')
+  if (actualVal === value) return { pass: true }
+  return {
+    pass: false,
+    message: `Response Body mismatch: expected field "${field}" to equal "${value}", got "${actualVal}"`
+  }
+}

package/src/endpoint.js

@@ -0,0 +1,3 @@
+export function buildEndpoint(baseUrl, path) {
+  return baseUrl.replace(/\/$/, '') + '/' + path.replace(/^\//, '')
+}

package/src/parser.js

@@ -0,0 +1,66 @@
+import { generateMessages } from '@cucumber/gherkin'
+import { IdGenerator, SourceMediaType } from '@cucumber/messages'
+import { readFile } from 'node:fs/promises'
+
+export async function parseFeatureFile(filePath) {
+  const source = await readFile(filePath, 'utf8')
+  const envelopes = generateMessages(source, filePath, SourceMediaType.TEXT_X_CUCUMBER_GHERKIN_PLAIN, {
+    includeSource: false,
+    includeGherkinDocument: false,
+    includePickles: true,
+    newId: IdGenerator.incrementing()
+  })
+
+  const errors = envelopes.filter(e => e.parseError)
+  if (errors.length > 0) throw new Error(errors[0].parseError.message.text)
+
+  return envelopes.filter(e => e.pickle).map(pickleToScenario)
+}
+
+function pickleToScenario(envelope) {
+  const pickle = envelope.pickle
+  const scenario = {
+    name: pickle.name,
+    method: null,
+    path: null,
+    requestBody: null,
+    expectedStatus: null,
+    expectedBody: null,
+    expectedFields: []
+  }
+
+  for (const step of pickle.steps) {
+    const text = step.text
+    const docContent = step.argument?.docString?.content ?? null
+
+    const actionMatch = text.match(/^I send a "([A-Z]+)" request to "([^"]+)"$/)
+    if (actionMatch) {
+      scenario.method = actionMatch[1]
+      scenario.path = actionMatch[2]
+      continue
+    }
+
+    if (/^the request body is:?$/.test(text) && docContent) {
+      scenario.requestBody = JSON.parse(docContent)
+      continue
+    }
+
+    const statusMatch = text.match(/^the response status should be (\d+)$/)
+    if (statusMatch) {
+      scenario.expectedStatus = parseInt(statusMatch[1], 10)
+      continue
+    }
+
+    if (/^the response body should be:?$/.test(text) && docContent) {
+      scenario.expectedBody = JSON.parse(docContent)
+      continue
+    }
+
+    const fieldMatch = text.match(/^the response body should contain field "([^"]+)" with value "([^"]+)"$/)
+    if (fieldMatch) {
+      scenario.expectedFields.push({ field: fieldMatch[1], value: fieldMatch[2] })
+    }
+  }
+
+  return scenario
+}

package/src/reporter.js

@@ -0,0 +1,27 @@
+const GREEN = '\x1b[32m'
+const RED = '\x1b[31m'
+const YELLOW = '\x1b[33m'
+const RESET = '\x1b[0m'
+
+export function reportScenario(scenarioName, endpoint, result) {
+  if (result.pass) {
+    console.log(`${GREEN}✅  Scenario: ${scenarioName}${RESET}`)
+    console.log(`    ${endpoint}`)
+  } else {
+    console.log(`${RED}❌  Scenario: ${scenarioName}${RESET}`)
+    console.log(`    ${endpoint}`)
+    for (const msg of result.messages) {
+      console.log(`${RED}    ${msg}${RESET}`)
+    }
+  }
+}
+
+export function reportSkipped(scenarioName) {
+  console.log(`${YELLOW}⚠️   Scenario skipped: ${scenarioName} — missing required steps (When + Then status)${RESET}`)
+}
+
+export function reportSummary(passed, failed) {
+  console.log('────────────────────────────────')
+  console.log(`  Results: ${passed} passed, ${failed} failed`)
+  console.log('────────────────────────────────')
+}

package/src/runner.js

@@ -0,0 +1,62 @@
+import axios from 'axios'
+import { buildEndpoint } from './endpoint.js'
+import { assertStatusCode, assertBodyExact, assertBodyField } from './assertions.js'
+
+export async function runScenario(scenario, baseUrl) {
+  const endpoint = buildEndpoint(baseUrl, scenario.path)
+  const messages = []
+
+  try {
+    const response = await axios({
+      method: scenario.method,
+      url: endpoint,
+      data: scenario.requestBody ?? undefined,
+      timeout: 30_000,
+      validateStatus: () => true,
+      responseType: 'text'
+    })
+
+    const statusResult = assertStatusCode(response.status, scenario.expectedStatus)
+    if (!statusResult.pass) messages.push(statusResult.message)
+
+    if (scenario.expectedBody !== null || scenario.expectedFields.length > 0) {
+      let body
+      try {
+        body = JSON.parse(response.data)
+      } catch {
+        messages.push(`Response body is not valid JSON: ${String(response.data).slice(0, 100)}`)
+        return { pass: false, messages }
+      }
+
+      if (scenario.expectedBody !== null) {
+        const bodyResult = assertBodyExact(body, scenario.expectedBody)
+        if (!bodyResult.pass) messages.push(bodyResult.message)
+      }
+
+      for (const { field, value } of scenario.expectedFields) {
+        const fieldResult = assertBodyField(body, field, value)
+        if (!fieldResult.pass) messages.push(fieldResult.message)
+      }
+    }
+  } catch (err) {
+    messages.push(`Connection failed: ${err.message}`)
+    return { pass: false, messages }
+  }
+
+  return { pass: messages.length === 0, messages }
+}
+
+export async function runAll(scenarios, baseUrl) {
+  let passed = 0
+  let failed = 0
+  const results = []
+
+  for (const scenario of scenarios) {
+    const result = await runScenario(scenario, baseUrl)
+    results.push({ scenario, ...result })
+    if (result.pass) passed++
+    else failed++
+  }
+
+  return { passed, failed, results }
+}