@postman-cse/onboarding-bootstrap 1.0.0 → 1.2.0

package/README.md

@@ -229,19 +229,22 @@ Scope:
 - Validate the bundled OpenAPI document with external and file resolution disabled during validation.
 - Match generated collection requests by method and canonical server/path candidates only; suffix path matching is not used.
 - Require one generated request for every eligible `paths` operation.
-- Validate response status codes, body presence, `Content-Type`, JSON response schemas, text/string schemas, and simple response header schemas.
-- Perform static checks for required non-security query/header parameters and required request bodies.
+- Validate response status codes, body presence, `Content-Type`, JSON response schemas (including asserted JSON Schema `format` values such as `uuid`, `date-time`, and `email`), text/string schemas, response header schemas with numeric/boolean coercion, and `Content-Length` consistency.
+- Check at runtime that each request carried credentials matching the operation's OpenAPI security requirements (API key header/query/cookie names, scheme-token authorization prefixes for every registered HTTP scheme including `Basic `, `Bearer `, and `Digest `, `Authorization` presence or `access_token` query for OAuth2/OpenID Connect).
+- Validate concrete request parameter values at runtime: scalar query/header/path/cookie parameters, decodable array parameters (exploded `form` arrays from repeated query keys; non-exploded `form`, `spaceDelimited`, and `pipeDelimited` arrays split on their delimiter; comma-joined `simple` header arrays), required-cookie presence, JSON-content parameters, and concrete JSON request bodies against the request-side OpenAPI schemas; placeholder values such as `<string>` and `{{variables}}` are skipped.
+- Perform static checks for required non-security query/header parameters, required request bodies, and request Content-Type; warn on incomplete or readOnly-bearing generated bodies and undocumented query parameters.
 
 Non-goals and limitations:
 
 - Swagger 2.0, OAS webhooks, callbacks, and arbitrary user-authored collection requests are not fully validated.
-- Security/auth requirements are not proven at runtime. API-key parameters derived from `securitySchemes` are warned as `CONTRACT_SECURITY_NOT_VALIDATED`.
-- Complex non-JSON object schemas, header `content`, unsupported schema dialects, unsupported keywords, and discriminator-heavy schemas fail closed instead of generating weak tests.
+- Runtime security checks prove credential presence and shape only; whether the server accepted the credential for the right reason is not proven, so security schemes are still warned as `CONTRACT_SECURITY_NOT_VALIDATED`. `mutualTLS` and unresolvable schemes are not checkable.
+- Header `content`, unsupported schema dialects, and unsupported keywords fail closed. Non-JSON object schemas, validator-engine compile refusals, and reference graphs past the embed cap skip schema validation with `CONTRACT_NONJSON_SCHEMA_NOT_VALIDATED`/`CONTRACT_SCHEMA_NOT_COMPILED` warnings while Content-Type and body-presence checks still run; a `discriminator` beside `oneOf`/`anyOf` of `$ref` members is enforced as a per-branch dispatch on its property, and other discriminator placements warn with `CONTRACT_DISCRIMINATOR_NOT_VALIDATED`.
 - Generated scripts target Newman/Postman runtime support for ES2020-compatible JavaScript and use compiled schemasafe IIFE validators. They do not use `pm.response.to.have.jsonSchema`, `eval`, or `new Function`.
 
 OpenAPI semantics:
 
 - OAS 3.0 `$ref` siblings are ignored, `nullable` is converted to JSON Schema unions, boolean exclusive min/max is converted, and response `writeOnly` properties are removed from response validation.
+- `format` values that schemasafe asserts (`date-time`, `date`, `time`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uri`, `uri-reference`, `uri-template`, `uuid`, `json-pointer`, `relative-json-pointer`, `regex`) are validated; `format: int32` integers gain numeric range bounds; other formats (`int64`, `byte`, `binary`, vendor formats) are treated as annotations and stripped. `contentEncoding`, `contentMediaType`, and `contentSchema` are treated as annotations.
 - OAS 3.1 `$ref` siblings are applied, the default dialect is JSON Schema 2020-12, supported `$schema` values are preserved, and unsupported custom dialects fail closed.
 
 Security and size limits:
@@ -280,6 +283,23 @@ Rollback behavior:
 | `CONTRACT_SECURITY_NOT_VALIDATED` | Security requirements were detected but dynamic tests cannot prove auth at runtime. | Run dedicated auth tests and review generated requests for required credentials. |
 | `CONTRACT_WEBHOOKS_NOT_VALIDATED` | OpenAPI webhooks were present but are not included in dynamic contract coverage. | Validate webhook behavior separately or model required behavior under `paths`. |
 | `CONTRACT_CALLBACKS_NOT_VALIDATED` | Operation callbacks were present but are not included in dynamic contract coverage. | Validate callback behavior separately or add dedicated tests. |
+| `CONTRACT_COOKIE_PARAM_NOT_VALIDATED` | A required cookie parameter cannot be included in generated requests, and the runtime test asserts its presence, so the contract run fails until the cookie is supplied at send time. | Attach the cookie via the cookie jar or a `Cookie` header in the run setup, or move the parameter to a header/query location. |
+| `CONTRACT_OPERATION_DEPRECATED` | A covered operation is marked `deprecated: true` in the OpenAPI document. | Plan removal of the deprecated operation or drop it from the spec when retired. |
+| `CONTRACT_REQUEST_BODY_INCOMPLETE` | A parseable generated request body is missing top-level required properties. | Fix the spec example or regenerate the collection so generated bodies satisfy the request schema. |
+| `CONTRACT_READONLY_PROPERTY_IN_REQUEST` | A generated request body includes properties the schema marks `readOnly`. | Remove readOnly properties from request examples; they belong in responses. |
+| `CONTRACT_UNDOCUMENTED_QUERY_PARAM` | A generated request sends a query parameter the operation does not declare. | Declare the parameter in the OpenAPI operation or remove it from the generated request. |
+| `CONTRACT_LINKS_NOT_VALIDATED` | Response links were present but link traversal is not part of dynamic contract coverage. | Validate linked operation chains with dedicated workflow tests. |
+| `CONTRACT_PARAM_SERIALIZATION_NOT_VALIDATED` | A parameter declares `allowReserved`, `content`, or a style/explode combination the runtime cannot decode. Exploded `form` arrays and non-exploded `form`/`spaceDelimited`/`pipeDelimited` arrays of scalars are decoded and validated, so they no longer warn. | Validate the remaining serialized forms with dedicated tests. |
+| `CONTRACT_NONJSON_SCHEMA_NOT_VALIDATED` | A non-JSON response media type declares an object schema that runtime tests cannot validate. | Validate XML or other non-JSON payloads with dedicated tests; Content-Type and body presence are still checked. |
+| `CONTRACT_REQUEST_SCHEMA_NOT_VALIDATED` | A JSON request body schema could not be compiled into a runtime request validator. | Simplify the unsupported request schema construct named in the warning. |
+| `CONTRACT_SCHEMA_NOT_COMPILED` | One schema could not be compiled by the validator engine, so its runtime check is skipped. | Review the named schema construct; other checks for the operation still run. |
+| `CONTRACT_EXAMPLE_SCHEMA_MISMATCH` | A media-type example does not validate against its own schema. | Fix the example or the schema so the spec is self-consistent; generated requests are built from these examples. |
+| `CONTRACT_ENCODING_MISMATCH` | A generated form-body field does not match its OpenAPI encoding object: a declared multipart per-part `contentType` is missing or different, a binary-typed field was not generated as a file part, or a field declaring a JSON `contentType` carries an unparseable value. | Regenerate the collection or align the encoding object with the intended part layout. |
+| `CONTRACT_ENCODING_HEADERS_NOT_VALIDATED` | A multipart encoding object declares per-part `headers`, which Postman formdata entries cannot carry, so they are not asserted. | Validate per-part headers with dedicated tests if the server depends on them. |
+| `CONTRACT_FORM_FIELD_SCHEMA_MISMATCH` | A generated urlencoded or multipart text value does not validate against its scalar property schema. | Fix the spec example feeding the generated body, or correct the property schema. |
+| `CONTRACT_DISCRIMINATOR_NOT_VALIDATED` | A `discriminator` has no sibling `oneOf`/`anyOf` of internal `$ref` members (typically allOf-parent inheritance), so its dispatch is not validated. | Restructure to the oneOf-plus-discriminator form, or rely on the still-validated composition keywords. |
+| `CONTRACT_HEADER_SCHEMA_NOT_VALIDATED` | A response header declares an object or otherwise undecodable schema, so its serialized value is checked for presence only. Arrays of scalars are split on commas and validated. | Use a scalar or array-of-scalars header schema, or validate the serialized header form with dedicated tests. |
+| `CONTRACT_PATH_PARAM_NOT_VALIDATED` | A path parameter declares a non-scalar schema or a serialization the runtime cannot decode, so its value is not validated. Scalar path parameters are validated at runtime against the resolved path segment. | Use a scalar path schema, or validate path value semantics with dedicated tests. |
 | `CONTRACT_DUPLICATE_OPERATION_MATCH` | Multiple OpenAPI operations share the same canonical request mapping candidate. | Disambiguate paths, server prefixes, or templated routes. |
 | `CONTRACT_DUPLICATE_OPERATION_REQUEST` | More than one generated request mapped to the same contract operation. | Disambiguate paths/operations or generated requests. |
 | `CONTRACT_OPERATION_COVERAGE_FAILED` | Generated contract collection did not cover every eligible operation. | Regenerate the collection or fix operation paths. |