{"library":"specmatic","title":"Specmatic Node.js Wrapper","type":"library","description":"Specmatic-node is an npm package that provides a Node.js wrapper for the core Specmatic executable JAR, enabling contract-driven development (CDD) workflows within JavaScript and TypeScript projects. It allows developers to easily install and manage the Specmatic JAR, run CLI commands, and programmatically interact with Specmatic's capabilities for API stubbing (smart mocks) and contract testing. The current stable version is 2.43.3. New patch and minor versions are released frequently, often several times a month, reflecting active development. Its key differentiators include enabling a 'no-code' approach to contract testing from OpenAPI/Swagger/AsyncAPI specifications and providing a smart stub server that can be configured programmatically to simulate API providers, facilitating independent development for API consumers. It bridges the JVM-based core Specmatic functionality with the Node.js ecosystem.","language":"javascript","status":"active","last_verified":"Sun Apr 19","install":{"commands":["npm install specmatic"],"cli":{"name":"specmatic","version":null}},"imports":["import { startHttpStub } from 'specmatic'","import { test } from 'specmatic'","import { setHttpStubExpectationJson } from 'specmatic'"],"auth":{"required":false,"env_vars":[]},"links":{"homepage":"https://specmatic.io","github":"https://github.com/specmatic/specmatic-node","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/specmatic","openapi_spec":null,"status_page":null,"smithery":null},"quickstart":{"code":"import { startHttpStub, setHttpStubExpectationJson, test, stopHttpStub } from 'specmatic';\nimport path from 'path'; // For resolving specmatic directory\n\n// Define the directory where your Specmatic OpenAPI/contract specification files are located.\n// For example, if your specs are in 'src/specmatic', use path.resolve(__dirname, 'src', 'specmatic')\nconst specmaticDir = path.resolve(__dirname, 'specmatic'); // Adjust this path as needed\n\nasync function runSpecmaticWorkflow() {\n  let stub;\n  try {\n    console.log(`Attempting to start Specmatic Stub server with specs from: ${specmaticDir}`);\n    // Start the Specmatic stub server, binding it to localhost:9000\n    // The specmaticDir is passed as an argument to load contract specifications.\n    stub = await startHttpStub('localhost', 9000, [specmaticDir]);\n    console.log(`Specmatic Stub running successfully on ${stub.url} (Process ID: ${stub.pid})`);\n\n    // Define and set a programmatic expectation for a GET /greeting endpoint on the stub.\n    // This allows the stub to respond with a specific JSON body for a matching request.\n    const expectation = {\n      \"method\": \"GET\",\n      \"path\": \"/greeting\",\n      \"response\": {\n        \"status\": 200,\n        \"headers\": {\n          \"Content-Type\": \"application/json\"\n        },\n        \"body\": {\"message\": \"Hello from Specmatic Stub!\"}\n      }\n    };\n    await setHttpStubExpectationJson(expectation, `http://localhost:${stub.port}`);\n    console.log('Stub expectation set for GET /greeting.');\n\n    // Simulate an API client interaction by fetching from the stub.\n    // In a real scenario, your application's HTTP client would call this.\n    console.log('Fetching from stub: GET /greeting');\n    const stubResponse = await fetch(`http://localhost:${stub.port}/greeting`);\n    const stubData = await stubResponse.json();\n    console.log('Received response from stub:', stubData);\n\n    // Run contract tests. This typically involves Specmatic verifying your API\n    // implementation against its OpenAPI specifications. For this example,\n    // we are testing against the running stub itself, which should pass if the spec is valid.\n    console.log(`Running contract tests against ${stub.url}`);\n    const testResult = await test(`http://localhost:${stub.port}`, [specmaticDir]);\n    console.log('Contract Test Results:', JSON.stringify(testResult, null, 2));\n\n  } catch (error) {\n    console.error('Specmatic workflow failed:', error);\n    process.exit(1);\n  } finally {\n    // Crucially, stop the Specmatic stub server to release resources and terminate the JAR process.\n    if (stub && stub.pid) {\n      console.log(`Stopping Specmatic Stub server (PID: ${stub.pid})...`);\n      await stopHttpStub(stub.pid);\n      console.log('Specmatic Stub stopped.');\n    }\n  }\n}\n\n// Execute the Specmatic workflow\nrunSpecmaticWorkflow();","lang":"typescript","description":"Demonstrates how to programmatically start a Specmatic stub server, define and set dynamic expectations, simulate client interaction with the stub, run contract tests against it, and ensure the stub is properly shut down.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}