@techspokes/typescript-wsdl-client 0.11.0 → 0.11.3

package/dist/test/mockData.js

@@ -0,0 +1,133 @@
+/**
+ * Mock Data Generator
+ *
+ * Generates realistic mock data trees from compiled catalog type metadata.
+ * Used by the test generator to create full default responses per operation
+ * so that generated tests pass out of the box.
+ *
+ * Pure logic — no I/O or side effects.
+ */
+/**
+ * Generates a mock primitive value based on the TypeScript type and property name.
+ * Uses contextual defaults based on common property names.
+ *
+ * @param tsType - The TypeScript type (string, number, boolean)
+ * @param propName - The property name for contextual defaults
+ * @returns A mock value of the appropriate type
+ */
+export function generateMockPrimitive(tsType, propName) {
+    const lower = propName.toLowerCase();
+    if (tsType === "boolean") {
+        if (lower === "success")
+            return true;
+        return true;
+    }
+    if (tsType === "number") {
+        if (lower.includes("id"))
+            return 1;
+        if (lower.includes("temperature") || lower.includes("temp"))
+            return 72;
+        if (lower.includes("humidity"))
+            return 65;
+        if (lower.includes("pressure"))
+            return 1013;
+        return 0;
+    }
+    // string type — use contextual defaults
+    if (lower === "zip" || lower === "zipcode" || lower === "postalcode")
+        return "10001";
+    if (lower === "city")
+        return "New York";
+    if (lower === "state")
+        return "NY";
+    if (lower === "country")
+        return "US";
+    if (lower === "description" || lower === "desciption")
+        return "Sample description";
+    if (lower === "responsetext")
+        return "Data Found";
+    if (lower === "weatherstationcity")
+        return "White Plains";
+    if (lower.includes("url") || lower.includes("picture"))
+        return "https://example.com/image.png";
+    if (lower.includes("wind"))
+        return "CALM";
+    if (lower.includes("visibility"))
+        return "10 miles";
+    if (lower.includes("windchill"))
+        return "72";
+    if (lower.includes("remarks"))
+        return "";
+    if (lower.includes("date") || lower.includes("time"))
+        return "2026-01-15T12:00:00.000Z";
+    if (lower.includes("temperature") || lower === "morninglow" || lower === "daytimehigh")
+        return "72";
+    if (lower.includes("nighttime") || lower.includes("daytime"))
+        return "0";
+    return "sample";
+}
+/**
+ * Generates a mock data object for a given type by walking the catalog type metadata.
+ *
+ * @param typeName - The type name to generate mock data for
+ * @param catalog - The compiled catalog with type metadata
+ * @param opts - Optional generation options
+ * @param visited - Set of visited type names for cycle detection (internal)
+ * @param depth - Current recursion depth (internal)
+ * @returns Mock data object matching the type structure
+ */
+export function generateMockData(typeName, catalog, opts, visited, depth) {
+    const maxDepth = opts?.maxDepth ?? 10;
+    const currentDepth = depth ?? 0;
+    const currentVisited = visited ?? new Set();
+    if (currentDepth >= maxDepth || currentVisited.has(typeName)) {
+        return {};
+    }
+    const childTypes = catalog.meta?.childType?.[typeName];
+    if (!childTypes || Object.keys(childTypes).length === 0) {
+        return {};
+    }
+    const propMeta = catalog.meta?.propMeta?.[typeName] ?? {};
+    const newVisited = new Set(currentVisited);
+    newVisited.add(typeName);
+    const result = {};
+    for (const [propName, propType] of Object.entries(childTypes)) {
+        const meta = propMeta[propName];
+        const isArray = meta?.max === "unbounded" || (typeof meta?.max === "number" && meta.max > 1);
+        // Check if it's a primitive type
+        if (propType === "string" || propType === "number" || propType === "boolean") {
+            const value = generateMockPrimitive(propType, propName);
+            result[propName] = isArray ? [value] : value;
+        }
+        else {
+            // Complex type — recurse
+            const childData = generateMockData(propType, catalog, opts, newVisited, currentDepth + 1);
+            result[propName] = isArray ? [childData] : childData;
+        }
+    }
+    return result;
+}
+/**
+ * Generates mock request and response data for all operations in the catalog.
+ *
+ * Response data uses the pre-unwrap shape (e.g. { WeatherDescription: [{...}] }
+ * not [{...}]) since the generated route handler calls unwrapArrayWrappers() at runtime.
+ *
+ * @param catalog - The compiled catalog with operations and type metadata
+ * @returns Map from operation name to { request, response } mock data
+ */
+export function generateAllOperationMocks(catalog) {
+    const result = new Map();
+    if (!catalog.operations)
+        return result;
+    for (const op of catalog.operations) {
+        const request = op.inputTypeName
+            ? generateMockData(op.inputTypeName, catalog)
+            : {};
+        const response = op.outputTypeName
+            ? generateMockData(op.outputTypeName, catalog)
+            : {};
+        result.set(op.name, { request, response });
+    }
+    return result;
+}

package/dist/util/imports.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Returns the file extension for the import mode
+ *
+ * @param {string} imports - Import mode (js, ts, or bare)
+ * @returns {string} - File extension with leading dot or empty string for bare
+ */
+export declare function getImportExtension(imports: string): string;
+/**
+ * Computes a relative import path from source to target
+ *
+ * @param {string} from - Source directory
+ * @param {string} to - Target file or directory
+ * @param {string} imports - Import mode (js, ts, or bare)
+ * @returns {string} - Relative import specifier with proper extension
+ */
+export declare function computeRelativeImport(from: string, to: string, imports: string): string;
+//# sourceMappingURL=imports.d.ts.map

package/dist/util/imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.d.ts","sourceRoot":"","sources":["../../src/util/imports.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAavF"}

package/dist/util/imports.js

@@ -0,0 +1,42 @@
+/**
+ * Shared Import Path Utilities
+ *
+ * Provides functions for computing relative import paths and file extensions
+ * across different import modes (js, ts, bare). Used by app scaffold, test
+ * generation, and other modules that need to emit import specifiers.
+ */
+import path from "node:path";
+/**
+ * Returns the file extension for the import mode
+ *
+ * @param {string} imports - Import mode (js, ts, or bare)
+ * @returns {string} - File extension with leading dot or empty string for bare
+ */
+export function getImportExtension(imports) {
+    if (imports === "js")
+        return ".js";
+    if (imports === "ts")
+        return ".ts";
+    return "";
+}
+/**
+ * Computes a relative import path from source to target
+ *
+ * @param {string} from - Source directory
+ * @param {string} to - Target file or directory
+ * @param {string} imports - Import mode (js, ts, or bare)
+ * @returns {string} - Relative import specifier with proper extension
+ */
+export function computeRelativeImport(from, to, imports) {
+    const rel = path.relative(from, to);
+    // Normalize to POSIX separators
+    const posix = rel.split(path.sep).join("/");
+    // Ensure it starts with ./ or ../
+    const prefixed = posix.startsWith(".") ? posix : `./${posix}`;
+    // Apply import extension rules
+    const ext = getImportExtension(imports);
+    if (ext) {
+        return prefixed + ext;
+    }
+    return prefixed;
+}

package/docs/cli-reference.md

@@ -122,6 +122,13 @@ The catalog is auto-placed alongside the first available output directory: `{cli
 | `--app-port` | `3000` | Default server port |
 | `--app-prefix` | (empty) | Route prefix |
 
+### Test Suite Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--test-dir` | (none) | Generate Vitest test suite in this directory (requires client, gateway) |
+| `--force-test` | `false` | Overwrite existing test files when using --test-dir |
+
 ### Pipeline Workflow
 
 Steps execute in order:
@@ -133,6 +140,7 @@ Steps execute in order:
 5. Generate OpenAPI (if --openapi-file)
 6. Generate gateway (if --gateway-dir)
 7. Scaffold app (if --init-app)
+8. Generate test suite (if --test-dir)
 
 All steps share the same parsed WSDL and compiled catalog.
 
@@ -163,6 +171,19 @@ npx wsdl-tsc pipeline \
   --init-app
 ```
 
+With generated test suite:
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source examples/minimal/weather.wsdl \
+  --client-dir tmp/client \
+  --openapi-file tmp/openapi.json \
+  --gateway-dir tmp/gateway \
+  --gateway-service-name weather \
+  --gateway-version-prefix v1 \
+  --test-dir tmp/tests
+```
+
 Client and OpenAPI only:
 
 ```bash

package/docs/decisions/001-test-generation.md

@@ -0,0 +1,36 @@
+# ADR 001: Generated Test Suite for Gateway Artifacts
+
+## Status
+
+Accepted
+
+## Context
+
+Users of generated Fastify gateways have no automated way to verify the generated code works. The only testing path is to manually write Vitest tests following the pattern in this project's own `test/integration/gateway-routes.test.ts`. The FST_ERR_FAILED_ERROR_SERIALIZATION bug (fixed in 0.11.1) proved that generated code can have subtle runtime issues that only surface under specific conditions. Generated tests would catch these immediately.
+
+## Decision
+
+Add an opt-in `--test-dir` flag to the pipeline command that generates a complete, runnable Vitest test suite validating all generated gateway artifacts.
+
+### Why generated tests (not a test library)
+
+A reusable test library would require users to configure imports, mock data, and test structure themselves. Generated tests are zero-config: they import the exact generated modules with correct relative paths, use mock data derived from the actual catalog types, and run immediately with `npx vitest run`.
+
+### Why full mocks (not placeholders)
+
+Placeholder mocks (empty objects, `TODO` comments) require manual effort before tests pass. Full mocks generated from catalog type metadata produce passing tests out of the box. Property names and types come from the compiled catalog's `meta.childType` map, so mock data matches the actual SOAP response shape.
+
+### Why skip-if-exists
+
+Test files are meant to be customized after generation. Re-running the pipeline should not overwrite user modifications. The `--force-test` flag provides an explicit override when regeneration is desired.
+
+### Relationship to operations.ts interface
+
+The generated `{ClassName}Operations` interface (from `operations.ts`) is the natural seam for mock injection. The mock client helper implements this interface with full default responses per operation. This matches the pattern established in `test/integration/gateway-routes.test.ts`.
+
+## Consequences
+
+- Users get immediate test coverage for generated gateway code
+- Mock data stays in sync with WSDL schema changes (regenerate to update)
+- Test files can be customized without risk of overwrite
+- Additional CLI flag and pipeline step increase the surface area to maintain

package/docs/testing.md

@@ -39,6 +39,7 @@ Unit tests cover pure functions with no I/O or side effects:
 - **`primitives.test.ts`** — `xsdToTsPrimitive()` covering all XSD types (string-like, boolean, integers, decimals, floats, dates, any)
 - **`errors.test.ts`** — `WsdlCompilationError` construction and `toUserMessage()` formatting
 - **`schema-alignment.test.ts`** — Cross-validates TypeScript types, JSON schemas, and catalog.json for consistency
+- **`mock-data.test.ts`** — `generateMockPrimitive()`, `generateMockData()`, `generateAllOperationMocks()` with cycle detection and array wrapping
 
 ### Writing Unit Tests
 
@@ -180,10 +181,79 @@ When `--openapi-flatten-array-wrappers false` is used, ArrayOf* types are emitte
 
 The `classifyError()` function puts `err.message` (a string) in the `details` field for connection and timeout errors, but the error JSON schema defines `details` as `object | null`. This causes Fastify serialization failures for 503/504 error responses. Test error classification directly via `classifyError()` rather than through Fastify's `inject()` for these error types.
 
+## Generated Test Suite
+
+The `--test-dir` flag generates a complete, runnable Vitest test suite that validates all generated gateway artifacts out of the box. This is the recommended way to verify generated code in consumer projects.
+
+### Generating Tests
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source service.wsdl \
+  --client-dir ./generated/client \
+  --openapi-file ./generated/openapi.json \
+  --gateway-dir ./generated/gateway \
+  --gateway-service-name myservice \
+  --gateway-version-prefix v1 \
+  --test-dir ./generated/tests
+```
+
+### Generated Structure
+
+```text
+{test-dir}/
+  vitest.config.ts
+  helpers/
+    mock-client.ts            createMockClient() with full default responses per operation
+    test-app.ts               createTestApp() Fastify bootstrap helper
+  gateway/
+    routes.test.ts            per-operation happy path (one test per route)
+    errors.test.ts            400/500/502/503/504 through Fastify
+    envelope.test.ts          SUCCESS/ERROR structure assertions
+    validation.test.ts        invalid payloads rejected per route
+  runtime/
+    classify-error.test.ts    classifyError() unit tests
+    envelope-builders.test.ts buildSuccessEnvelope/buildErrorEnvelope
+    unwrap.test.ts            unwrapArrayWrappers (only when ArrayOf* wrappers exist)
+```
+
+### Running Generated Tests
+
+```bash
+npx vitest run --config ./generated/tests/vitest.config.ts
+```
+
+### Skip-if-Exists Behavior
+
+Test files that already exist are skipped by default. This allows you to customize generated tests without losing changes on regeneration. Use `--force-test` to overwrite all test files.
+
+### Mock Client
+
+The generated `helpers/mock-client.ts` creates a fully typed mock client with default responses for every operation. Override individual methods for specific test scenarios:
+
+```typescript
+import { createMockClient } from "./helpers/mock-client.js";
+
+const client = createMockClient({
+  GetCityWeatherByZIP: async () => ({
+    response: { GetCityWeatherByZIPResult: { Success: false, WeatherID: 0 } },
+    headers: {},
+  }),
+});
+```
+
+Mock responses use the pre-unwrap SOAP wrapper shape. The generated `unwrapArrayWrappers()` function handles conversion at runtime.
+
 ## For Consumer Projects
 
 If you're using wsdl-tsc as a dependency and want to test your integration:
 
+1. Generate code with `npx wsdl-tsc pipeline --test-dir ./tests` to get a ready-to-run test suite
+2. Run `npx vitest run --config ./tests/vitest.config.ts` to verify everything works
+3. Customize generated tests as needed (they won't be overwritten on regeneration)
+
+Alternatively, write tests manually:
+
 1. Generate code with `npx wsdl-tsc pipeline`
 2. Import the operations interface from `operations.ts`
 3. Create a mock client implementing the interface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.11.0",
+  "version": "0.11.3",
   "description": "Generate type-safe TypeScript SOAP clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways from WSDL/XSD definitions.",
   "keywords": [
     "wsdl",