japa-openapi-assertions 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# @drew-daniels/japa-openapi-assertions
+
+OpenAPI 3.1 assertions plugin for [Japa](https://japa.dev) test framework. Validate your API responses against OpenAPI specifications with full OpenAPI 3.1 support.
+
+## Why This Fork?
+
+This package is a fork of [`@japa/openapi-assertions`](https://japa.dev/docs/plugins/openapi-assertions) created to add **OpenAPI 3.1 support**. The original package uses [`api-contract-validator`](https://github.com/PayU/api-contract-validator) under the hood, which only supports OpenAPI 3.0.
+
+OpenAPI 3.1 introduced significant changes that break compatibility with OpenAPI 3.0 tooling. This fork replaces the underlying validation engine with [AJV](https://ajv.js.org/) configured for [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html), providing native support for OpenAPI 3.1 specifications.
+
+## OpenAPI 3.0 vs 3.1: Key Differences
+
+OpenAPI 3.1 aligns fully with JSON Schema Draft 2020-12, which introduced several breaking changes from the modified JSON Schema subset used in OpenAPI 3.0:
+
+### Nullable Types
+
+The `nullable` keyword was removed. Use JSON Schema type arrays instead:
+
+```yaml
+# OpenAPI 3.0
+type: string
+nullable: true
+
+# OpenAPI 3.1
+type: ["string", "null"]
+```
+
+### Exclusive Min/Max
+
+Boolean modifiers changed to numeric values:
+
+```yaml
+# OpenAPI 3.0
+minimum: 0
+exclusiveMinimum: true
+
+# OpenAPI 3.1
+exclusiveMinimum: 0
+```
+
+### $ref Behavior
+
+OpenAPI 3.1 allows sibling keywords alongside `$ref`, eliminating the need for `allOf` workarounds:
+
+```yaml
+# OpenAPI 3.0 (workaround required)
+allOf:
+  - $ref: '#/components/schemas/Pet'
+  - description: A pet with extra info
+
+# OpenAPI 3.1 (direct usage)
+$ref: '#/components/schemas/Pet'
+description: A pet with extra info
+```
+
+### Examples
+
+The `example` keyword is deprecated in favor of `examples` (array format):
+
+```yaml
+# OpenAPI 3.0
+example: "Fluffy"
+
+# OpenAPI 3.1
+examples:
+  - "Fluffy"
+  - "Buddy"
+```
+
+For a complete list of changes, see the [OpenAPI Initiative migration guide](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0).
+
+## Backward Compatibility
+
+**This package is designed for OpenAPI 3.1 specifications.** It may work with some OpenAPI 3.0 specs, but compatibility is not guaranteed due to the fundamental differences in how schemas are validated:
+
+| Feature | OpenAPI 3.0 Spec | This Package |
+|---------|------------------|--------------|
+| `nullable: true` | Supported in 3.0 | Not supported - use `type: ["string", "null"]` |
+| `type: ["string", "null"]` | Not valid in 3.0 | Fully supported |
+| `exclusiveMinimum: true` | Supported in 3.0 | Not supported - use numeric value |
+| `$ref` with siblings | Not valid in 3.0 | Fully supported |
+
+If you need OpenAPI 3.0 support, use the original [`@japa/openapi-assertions`](https://www.npmjs.com/package/@japa/openapi-assertions) package.
+
+## Installation
+
+```bash
+npm install @drew-daniels/japa-openapi-assertions
+```
+
+### Peer Dependencies
+
+This plugin requires:
+- `@japa/assert` ^4.0.0
+- `@japa/runner` ^3.0.0 || ^4.0.0 || ^5.0.0
+
+```bash
+npm install @japa/assert @japa/runner
+```
+
+## Setup
+
+Configure the plugin in your Japa configuration file:
+
+```typescript
+// tests/bootstrap.ts
+import { assert } from '@japa/assert'
+import { apiClient } from '@japa/api-client'
+import { openapi } from '@drew-daniels/japa-openapi-assertions'
+
+export const plugins = [
+  assert(),
+  openapi({
+    schemas: [new URL('../openapi.json', import.meta.url)],
+    reportCoverage: true,
+  }),
+  apiClient(),
+]
+```
+
+## Usage
+
+Use the `isValidApiResponse` assertion method to validate responses against your OpenAPI specification:
+
+```typescript
+import { test } from '@japa/runner'
+
+test.group('Pets API', () => {
+  test('list all pets', async ({ client, assert }) => {
+    const response = await client.get('/pets')
+
+    response.assertStatus(200)
+    assert.isValidApiResponse(response)
+  })
+
+  test('get a single pet', async ({ client, assert }) => {
+    const response = await client.get('/pets/123')
+
+    response.assertStatus(200)
+    assert.isValidApiResponse(response)
+  })
+
+  test('create a pet', async ({ client, assert }) => {
+    const response = await client
+      .post('/pets')
+      .json({ name: 'Fluffy', tag: 'cat' })
+
+    response.assertStatus(201)
+    assert.isValidApiResponse(response)
+  })
+})
+```
+
+### Validation Behavior
+
+The plugin validates:
+
+- **Path matching**: Ensures the request path exists in your OpenAPI spec (supports parameterized paths like `/pets/{petId}`)
+- **HTTP method**: Validates the method is defined for the matched path
+- **Status code**: Checks that a response schema exists for the returned status
+- **Response body**: Validates the response body against the JSON schema defined in your spec
+
+If validation fails, a detailed `AssertionError` is thrown with information about what didn't match.
+
+## Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `schemas` | `(string \| URL)[]` | **Required.** Paths to OpenAPI specification files (JSON format) |
+| `reportCoverage` | `boolean` | Print coverage report to console on process exit |
+| `exportCoverage` | `boolean` | Export coverage data to `coverage.json` on process exit |
+
+### Coverage Reporting
+
+Enable coverage tracking to see which API endpoints have been tested:
+
+```typescript
+openapi({
+  schemas: ['./openapi.json'],
+  reportCoverage: true,
+  exportCoverage: true,
+})
+```
+
+The coverage report shows:
+- Total endpoints defined in your spec
+- Number of endpoints tested
+- List of untested endpoints
+- Coverage percentage
+
+## Supported HTTP Clients
+
+The plugin automatically detects and parses responses from popular HTTP client libraries:
+
+| Library | Support |
+|---------|---------|
+| [@japa/api-client](https://japa.dev/docs/plugins/api-client) | Full support |
+| [Axios](https://axios-http.com/) | Full support |
+| [Supertest](https://github.com/ladjs/supertest) | Full support |
+
+### Response Format Detection
+
+The plugin inspects the response object to determine which format to use:
+
+- **Japa api-client**: Detected by `request` and `statusCode` properties
+- **Axios**: Detected by `data`, `config`, and `status` properties
+- **Supertest**: Detected by `body`, `req`, and `statusCode` properties
+
+## Requirements
+
+- Node.js >= 20.6.0
+- OpenAPI 3.1.x specification in JSON format
+
+## Technical Details
+
+This package uses:
+- [AJV](https://ajv.js.org/) with JSON Schema 2020-12 support for schema validation
+- [ajv-formats](https://github.com/ajv-validator/ajv-formats) for format validation (email, uri, date-time, etc.)
+- [@seriousme/openapi-schema-validator](https://github.com/seriousme/openapi-schema-validator) for OpenAPI document validation
+
+All `$ref` pointers are resolved locally before validation, supporting references like `$ref: '#/components/schemas/Pet'`.
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/drew-daniels/japa-openapi-assertions](https://github.com/drew-daniels/japa-openapi-assertions).
+
+## Credits
+
+This package is a fork of the original [@japa/openapi-assertions](https://japa.dev/docs/plugins/openapi-assertions) by the Japa team.
+
+## Further Reading
+
+- [OpenAPI 3.1 Migration Guide](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)
+- [Upgrading from OpenAPI 3.0 to 3.1](https://learn.openapis.org/upgrading/v3.0-to-v3.1.html)
+- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html)
+- [Japa Testing Framework](https://japa.dev/)

package/build/coverage.d.ts

@@ -0,0 +1,53 @@
+import type { CoverageEntry } from './types.js';
+interface CoverageRecord {
+    route: string;
+    method: string;
+    status: string;
+}
+/**
+ * Tracks API endpoint coverage during test runs.
+ */
+export declare class CoverageTracker {
+    private allEndpoints;
+    private covered;
+    private reportOnExit;
+    private exportOnExit;
+    private exitHandlerRegistered;
+    /**
+     * Register all endpoints from the OpenAPI spec for coverage tracking.
+     */
+    registerEndpoints(entries: CoverageEntry[]): void;
+    /**
+     * Record that an endpoint was covered during testing.
+     */
+    recordCoverage(route: string, method: string, status: string): void;
+    /**
+     * Get list of uncovered endpoints.
+     */
+    getUncovered(): CoverageRecord[];
+    /**
+     * Get coverage statistics.
+     */
+    getStats(): {
+        total: number;
+        covered: number;
+        percentage: number;
+    };
+    /**
+     * Enable reporting on process exit.
+     */
+    enableReporting(report: boolean, exportFile: boolean): void;
+    /**
+     * Print coverage report to console.
+     */
+    report(): void;
+    /**
+     * Export coverage data to JSON file.
+     */
+    export(filePath?: string): void;
+    private makeKey;
+    private registerExitHandler;
+}
+export declare const coverageTracker: CoverageTracker;
+export {};
+//# sourceMappingURL=coverage.d.ts.map

package/build/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,UAAU,cAAc;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,qBAAqB,CAAiB;IAE9C;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,IAAI;IAYjD;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAKnE;;OAEG;IACH,YAAY,IAAI,cAAc,EAAE;IAMhC;;OAEG;IACH,QAAQ,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAQlE;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG,IAAI;IAS3D;;OAEG;IACH,MAAM,IAAI,IAAI;IAuCd;;OAEG;IACH,MAAM,CAAC,QAAQ,GAAE,MAAwB,GAAG,IAAI;IAYhD,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,mBAAmB;CAY5B;AAGD,eAAO,MAAM,eAAe,iBAAwB,CAAA"}

package/build/coverage.js

@@ -0,0 +1,123 @@
+import { writeFileSync } from 'node:fs';
+import chalk from 'chalk';
+/**
+ * Tracks API endpoint coverage during test runs.
+ */
+export class CoverageTracker {
+    allEndpoints = [];
+    covered = new Set();
+    reportOnExit = false;
+    exportOnExit = false;
+    exitHandlerRegistered = false;
+    /**
+     * Register all endpoints from the OpenAPI spec for coverage tracking.
+     */
+    registerEndpoints(entries) {
+        for (const entry of entries) {
+            for (const status of entry.statuses) {
+                this.allEndpoints.push({
+                    route: entry.route,
+                    method: entry.method,
+                    status,
+                });
+            }
+        }
+    }
+    /**
+     * Record that an endpoint was covered during testing.
+     */
+    recordCoverage(route, method, status) {
+        const key = this.makeKey(route, method, status);
+        this.covered.add(key);
+    }
+    /**
+     * Get list of uncovered endpoints.
+     */
+    getUncovered() {
+        return this.allEndpoints.filter((e) => !this.covered.has(this.makeKey(e.route, e.method, e.status)));
+    }
+    /**
+     * Get coverage statistics.
+     */
+    getStats() {
+        const total = this.allEndpoints.length;
+        const covered = this.covered.size;
+        const percentage = total > 0 ? Math.round((covered / total) * 100) : 100;
+        return { total, covered, percentage };
+    }
+    /**
+     * Enable reporting on process exit.
+     */
+    enableReporting(report, exportFile) {
+        this.reportOnExit = report;
+        this.exportOnExit = exportFile;
+        if ((report || exportFile) && !this.exitHandlerRegistered) {
+            this.registerExitHandler();
+        }
+    }
+    /**
+     * Print coverage report to console.
+     */
+    report() {
+        const uncovered = this.getUncovered();
+        const stats = this.getStats();
+        console.log('');
+        console.log(chalk.bold('API Coverage Report'));
+        console.log(chalk.dim('─'.repeat(50)));
+        if (uncovered.length === 0) {
+            console.log(chalk.green('✓ All endpoints covered!'));
+        }
+        else {
+            console.log(chalk.yellow(`Uncovered endpoints (${uncovered.length}):`));
+            console.log('');
+            // Group by route for cleaner output
+            const byRoute = new Map();
+            for (const endpoint of uncovered) {
+                const existing = byRoute.get(endpoint.route) || [];
+                existing.push(endpoint);
+                byRoute.set(endpoint.route, existing);
+            }
+            for (const [route, endpoints] of byRoute) {
+                console.log(chalk.dim(`  ${route}`));
+                for (const ep of endpoints) {
+                    console.log(`    ${chalk.cyan(ep.method.padEnd(7))} ${chalk.dim(ep.status)}`);
+                }
+            }
+        }
+        console.log('');
+        console.log(chalk.dim('─'.repeat(50)));
+        console.log(`Coverage: ${stats.covered}/${stats.total} endpoints `
+            + `(${chalk.bold(stats.percentage + '%')})`);
+        console.log('');
+    }
+    /**
+     * Export coverage data to JSON file.
+     */
+    export(filePath = 'coverage.json') {
+        const uncovered = this.getUncovered();
+        const data = uncovered.map((e) => ({
+            route: e.route,
+            method: e.method,
+            statuses: e.status,
+        }));
+        writeFileSync(filePath, JSON.stringify(data, null, 2));
+        console.log(chalk.dim(`Coverage data exported to ${filePath}`));
+    }
+    makeKey(route, method, status) {
+        return `${method.toUpperCase()}:${route}:${status}`;
+    }
+    registerExitHandler() {
+        this.exitHandlerRegistered = true;
+        process.on('beforeExit', () => {
+            if (this.reportOnExit) {
+                this.report();
+            }
+            if (this.exportOnExit) {
+                this.export();
+            }
+        });
+    }
+}
+// Singleton instance for global coverage tracking
+export const coverageTracker = new CoverageTracker();
+//# sourceMappingURL=coverage.js.map

package/build/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -0,0 +1,33 @@
+import type { PluginConfig } from './types.js';
+export { OpenApiAssertions } from './openapi_assertions.js';
+export type { PluginConfig } from './types.js';
+declare module '@japa/assert' {
+    interface Assert {
+        isValidApiResponse(response: unknown): void;
+    }
+}
+/**
+ * OpenAPI assertions plugin for Japa.
+ *
+ * This plugin validates HTTP responses against OpenAPI 3.0/3.1 specifications.
+ * It's a drop-in replacement for @japa/openapi-assertions with full OpenAPI 3.1 support.
+ *
+ * @example
+ * ```typescript
+ * import { openapi } from '@drew-daniels/japa-openapi-assertions'
+ *
+ * export const plugins = [
+ *   assert(),
+ *   openapi({
+ *     schemas: ['./openapi.json'],
+ *     reportCoverage: true,
+ *   }),
+ *   apiClient(),
+ * ]
+ * ```
+ *
+ * @param options - Plugin configuration
+ * @returns Japa plugin function
+ */
+export declare function openapi(options: PluginConfig): () => void;
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,MAAM;QACd,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;KAC5C;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,YAAY,cAc5C"}

package/build/index.js

@@ -0,0 +1,42 @@
+import { Assert } from '@japa/assert';
+import { OpenApiAssertions } from './openapi_assertions.js';
+// Re-export types and classes
+export { OpenApiAssertions } from './openapi_assertions.js';
+/**
+ * OpenAPI assertions plugin for Japa.
+ *
+ * This plugin validates HTTP responses against OpenAPI 3.0/3.1 specifications.
+ * It's a drop-in replacement for @japa/openapi-assertions with full OpenAPI 3.1 support.
+ *
+ * @example
+ * ```typescript
+ * import { openapi } from '@drew-daniels/japa-openapi-assertions'
+ *
+ * export const plugins = [
+ *   assert(),
+ *   openapi({
+ *     schemas: ['./openapi.json'],
+ *     reportCoverage: true,
+ *   }),
+ *   apiClient(),
+ * ]
+ * ```
+ *
+ * @param options - Plugin configuration
+ * @returns Japa plugin function
+ */
+export function openapi(options) {
+    // Register specs immediately (async loading happens in background)
+    OpenApiAssertions.registerSpecs(options.schemas, {
+        reportCoverage: options.reportCoverage,
+        exportCoverage: options.exportCoverage,
+    });
+    // Return the Japa plugin function
+    return function japaOpenapiPlugin() {
+        // Register the assertion macro
+        Assert.macro('isValidApiResponse', function (response) {
+            return new OpenApiAssertions().isValidResponse(response);
+        });
+    };
+}
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAG3D,8BAA8B;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAU3D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,OAAO,CAAC,OAAqB;IAC3C,mEAAmE;IACnE,iBAAiB,CAAC,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE;QAC/C,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC,CAAA;IAEF,kCAAkC;IAClC,OAAO,SAAS,iBAAiB;QAC/B,+BAA+B;QAC/B,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE,UAAwB,QAAiB;YAC1E,OAAO,IAAI,iBAAiB,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAA;QAC1D,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC"}

package/build/openapi_assertions.d.ts

@@ -0,0 +1,49 @@
+interface RegisterOptions {
+    reportCoverage?: boolean;
+    exportCoverage?: boolean;
+}
+/**
+ * OpenAPI assertions for validating HTTP responses against OpenAPI specifications.
+ *
+ * This is a drop-in replacement for @japa/openapi-assertions with OpenAPI 3.1 support.
+ */
+export declare class OpenApiAssertions {
+    /**
+     * Compiled validators from registered specs.
+     */
+    private static validators;
+    /**
+     * Flag indicating if specs have been registered.
+     */
+    private static hasRegistered;
+    /**
+     * Coverage options.
+     */
+    private static coverageOptions;
+    /**
+     * Register OpenAPI specs to validate responses against.
+     * This method is SYNCHRONOUS to match the original @japa/openapi-assertions API.
+     *
+     * @param schemaPathsOrURLs - Paths or URLs to OpenAPI spec files
+     * @param options - Coverage reporting options
+     */
+    static registerSpecs(schemaPathsOrURLs: (string | URL)[], options?: RegisterOptions): void;
+    /**
+     * Reset the assertions state (useful for testing).
+     */
+    static reset(): void;
+    /**
+     * Get validators, throwing if not registered.
+     */
+    private static getValidators;
+    /**
+     * Validate that a response matches the OpenAPI specification.
+     * This method is SYNCHRONOUS to match the original @japa/openapi-assertions API.
+     *
+     * @param response - HTTP response object from axios, supertest, or Japa api-client
+     * @throws AssertionError if the response does not match the spec
+     */
+    isValidResponse(response: unknown): void;
+}
+export {};
+//# sourceMappingURL=openapi_assertions.d.ts.map

package/build/openapi_assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi_assertions.d.ts","sourceRoot":"","sources":["../src/openapi_assertions.ts"],"names":[],"mappings":"AAQA,UAAU,eAAe;IACvB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU,CAAkC;IAE3D;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa,CAAiB;IAE7C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe,CAAsB;IAEpD;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAClB,iBAAiB,EAAE,CAAC,MAAM,GAAG,GAAG,CAAC,EAAE,EACnC,OAAO,GAAE,eAAoB,GAC5B,IAAI;IAuBP;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAMpB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAU5B;;;;;;OAMG;IACH,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;CAsDzC"}

package/build/openapi_assertions.js

@@ -0,0 +1,114 @@
+import { AssertionError } from 'node:assert';
+import { fileURLToPath } from 'node:url';
+import { buildValidatorsSync } from './schema_builder.js';
+import { validateResponse, parseResponse } from './response_validator.js';
+import { matchPath } from './path_matcher.js';
+import { coverageTracker } from './coverage.js';
+/**
+ * OpenAPI assertions for validating HTTP responses against OpenAPI specifications.
+ *
+ * This is a drop-in replacement for @japa/openapi-assertions with OpenAPI 3.1 support.
+ */
+export class OpenApiAssertions {
+    /**
+     * Compiled validators from registered specs.
+     */
+    static validators = null;
+    /**
+     * Flag indicating if specs have been registered.
+     */
+    static hasRegistered = false;
+    /**
+     * Coverage options.
+     */
+    static coverageOptions = {};
+    /**
+     * Register OpenAPI specs to validate responses against.
+     * This method is SYNCHRONOUS to match the original @japa/openapi-assertions API.
+     *
+     * @param schemaPathsOrURLs - Paths or URLs to OpenAPI spec files
+     * @param options - Coverage reporting options
+     */
+    static registerSpecs(schemaPathsOrURLs, options = {}) {
+        this.hasRegistered = true;
+        this.coverageOptions = options;
+        // Convert URLs to file paths
+        const paths = schemaPathsOrURLs.map((p) => p instanceof URL ? fileURLToPath(p) : p);
+        // Build validators synchronously
+        const result = buildValidatorsSync(paths);
+        this.validators = result.validators;
+        // Register coverage entries
+        if (options.reportCoverage || options.exportCoverage) {
+            coverageTracker.registerEndpoints(result.coverageEntries);
+            coverageTracker.enableReporting(options.reportCoverage ?? false, options.exportCoverage ?? false);
+        }
+    }
+    /**
+     * Reset the assertions state (useful for testing).
+     */
+    static reset() {
+        this.validators = null;
+        this.hasRegistered = false;
+        this.coverageOptions = {};
+    }
+    /**
+     * Get validators, throwing if not registered.
+     */
+    static getValidators() {
+        if (!this.validators) {
+            throw new Error('Cannot validate responses without defining API schemas. '
+                + 'Please configure the plugin with schemas.');
+        }
+        return this.validators;
+    }
+    /**
+     * Validate that a response matches the OpenAPI specification.
+     * This method is SYNCHRONOUS to match the original @japa/openapi-assertions API.
+     *
+     * @param response - HTTP response object from axios, supertest, or Japa api-client
+     * @throws AssertionError if the response does not match the spec
+     */
+    isValidResponse(response) {
+        if (!OpenApiAssertions.hasRegistered) {
+            throw new Error('Cannot validate responses without defining API schemas. '
+                + 'Please configure the plugin with schemas.');
+        }
+        const validators = OpenApiAssertions.getValidators();
+        const result = validateResponse(response, validators);
+        // Record coverage if enabled
+        if (OpenApiAssertions.coverageOptions.reportCoverage
+            || OpenApiAssertions.coverageOptions.exportCoverage) {
+            try {
+                const parsed = parseResponse(response);
+                const specPaths = Object.keys(validators);
+                const pathMatch = matchPath(parsed.path, specPaths);
+                if (pathMatch) {
+                    coverageTracker.recordCoverage(pathMatch.matched, parsed.method, String(parsed.status));
+                }
+            }
+            catch {
+                // Ignore coverage tracking errors
+            }
+        }
+        if (!result.valid) {
+            const errorDetails = result.errors
+                ?.map((e) => {
+                let msg = e.path ? `${e.path}: ${e.message}` : e.message;
+                if (e.expected !== undefined) {
+                    msg += ` (expected: ${JSON.stringify(e.expected)})`;
+                }
+                if (e.actual !== undefined) {
+                    msg += ` (actual: ${JSON.stringify(e.actual)})`;
+                }
+                return msg;
+            })
+                .join('\n  ');
+            throw new AssertionError({
+                message: `Response does not match API schema:\n  ${errorDetails}`,
+                actual: result.errors,
+                expected: 'valid response matching OpenAPI schema',
+            });
+        }
+    }
+}
+//# sourceMappingURL=openapi_assertions.js.map