@@ -13,67 +13,72 @@ import type { CollectionFormat, RequestExt, Resolver, ResolverConfig } from "./t
 import { ValidationError } from "./validation-error.js";
 
 /**
- * Class containing all the expectations that can be run on the request.
+ * Assertions against one incoming request. A mismatch throws {@link ValidationError}
+ * with expected and actual values; successful assertions return normally.
  */
 export class RequestExpectation {
+  /** Binds assertions to the supplied request without copying its data. */
   public constructor(private originalRequest: RequestExt) {}
   /**
-   * Expect the raw body of the request to match the given string.
-   * @param rawBody Raw request body.
-   * @throws {ValidationError} if there is an error.
+   * Requires strict equality of raw strings or Buffer bytes, without converting between them.
+   * An undefined expectation requires an empty raw payload.
+   * @throws {ValidationError} when the payload differs.
    */
   public rawBodyEquals(expectedRawBody: string | Buffer | undefined): void {
     validateRawBodyEquals(this.originalRequest, expectedRawBody);
   }
 
   /**
-   * Expect the body of the request to match the given object.
-   * @param rawBody Raw request body.
-   * @throws {ValidationError} if there is an error.
+   * Compares the parsed body using {@link matchValues}, including nested value matchers.
+   * A null or undefined expectation instead requires an empty raw payload.
+   * @throws {ValidationError} when the payload differs.
    */
   public bodyEquals(expectedRawBody: unknown | undefined): void {
     validateBodyEquals(this.originalRequest, expectedRawBody);
   }
 
   /**
-   * Expect the coerced body of the request to match the given object.
-   * @param rawBody Raw request body.
-   * @throws {ValidationError} if there is an error.
+   * JSON-round-trips the actual body and normalizes UTC datetime strings before
+   * matcher-aware comparison. Removes 3–7 fractional digits and replaces zero offsets
+   * with `Z`; the expected value is not normalized.
+   * A null or undefined expectation requires an empty raw payload.
+   * @throws {ValidationError} when the payload differs.
    */
   public coercedBodyEquals(expectedRawBody: unknown | undefined): void {
     validateCoercedDateBodyEquals(this.originalRequest, expectedRawBody);
   }
 
   /**
-   * Expect the body of the request to be empty.
-   * @throws {ValidationError} if there is an error.
+   * Requires an empty raw body and rejects a nonempty parsed Buffer.
+   * Other parsed values do not determine emptiness.
+   * @throws {ValidationError} when a body is present.
    */
   public bodyEmpty(): void {
     validateBodyEmpty(this.originalRequest);
   }
 
   /**
-   * Expect the body of the request to be not empty.
+   * Requires a nonempty raw payload, falling back to the parsed Buffer when rawBody is empty.
    * @throws {ValidationError} if there is an error.
    */
   public bodyNotEmpty(): void {
     validateBodyNotEmpty(this.originalRequest);
   }
 
   /**
-   * Expect the header of the request contains the expected key/value pair
-   * @param headerName Key expected in header
-   * @param expectedValue Values expected in header
-   * @throws {ValidationError} if there is an error.
+   * Requires the parsed header value to equal the expected string exactly.
+   * Use a lowercase header name; other headers are not checked.
+   * @throws {ValidationError} when the header is absent or differs.
    */
   public containsHeader(headerName: string, expectedValue: string): void {
     validateHeader(this.originalRequest, headerName, expectedValue);
   }
 
   /**
-   * Expect the query string of the request contains the expected name/value pair.
-   * @param paramName Name of the query parameter.
-   * @param expectedValue Value expected of the query parameter.
+   * Requires a query parameter to equal the expected string or encoded collection.
+   * For arrays, specify `multi` for repeated parameters or a delimiter format;
+   * array element order is significant. Other query parameters are not checked.
+   * @throws {ValidationError} when the parameter is absent or differs.
    */
   public containsQueryParam(
     paramName: string,
@@ -84,9 +89,10 @@ export class RequestExpectation {
   }
 
   /**
-   * Check if two requests are equal
-   * @param actual Actual value
-   * @param expected Expected value
+   * Compares arbitrary values using {@link matchValues}, accepting matchers in the
+   * expected tree. The failure message includes the first mismatching value's path.
+   * @param message Prefix for the mismatch detail.
+   * @throws {ValidationError} when the values do not match.
    */
   public deepEqual(actual: unknown, expected: unknown, message = "Values not deep equal"): void {
     const result = matchValues(actual, expected);
@@ -96,12 +102,11 @@ export class RequestExpectation {
   }
 
   /**
-   * Expect the body of the request to be semantically equivalent to the provided XML.
-   * Accepts a plain string or a Resolver (e.g. from `xml\`...\``).
-   * When a Resolver with matchers is provided, matcher-aware comparison is used.
-   * The XML declaration prefix will automatically be added.
-   * @param expectedBody expected XML body as a string or Resolver.
-   * @param config resolver config (required when expectedBody is a Resolver).
+   * Compares parsed XML using string-valued tag content. Plain strings have an XML declaration
+   * added; Resolvers supply serialized XML, with template matchers recovered through getMatchers.
+   * @param expectedBody XML string or Resolver. The xml helper returns a MockBody; for tagged
+   * XML, narrow its rawContent to a Resolver and pass that, not the body wrapper.
+   * @param config Context for resolving dynamic values; defaults to an empty base URL.
    * @throws {ValidationError} if there is an error.
    */
   public xmlBodyEquals(expectedBody: string | Resolver, config?: ResolverConfig): void {
 
@@ -10,8 +10,18 @@
 /** Symbol used to identify matcher objects */
 export const MatcherSymbol: unique symbol = Symbol.for("SpectorMatcher");
 
-/** Result of a match operation */
-export type MatchResult = { pass: true } | { pass: false; message: string };
+/** Comparison outcome; narrow on `pass` before reading the failure message. */
+export type MatchResult =
+  | {
+      /** The actual value satisfies the expectation. */
+      pass: true;
+    }
+  | {
+      /** The actual value does not satisfy the expectation. */
+      pass: false;
+      /** Reason for failure, including a value path when returned by matchValues. */
+      message: string;
+    };
 
 const OK: MatchResult = Object.freeze({ pass: true });
 
@@ -43,14 +53,19 @@ export interface MockValueMatcher<T = unknown> {
 
 /** Configuration available to matchers at runtime */
 export interface MatcherConfig {
+  /** Server origin used by URL matchers; defaults to an empty string when no config is supplied. */
   baseUrl: string;
 }
 
 const emptyConfig: MatcherConfig = { baseUrl: "" };
 
+/** Behavior supplied to createMatcher, optionally created by a factory that captures runtime config. */
 interface MatcherImpl<T> {
+  /** Checks the incoming value and returns an outcome rather than throwing for a mismatch. */
   check(actual: unknown): MatchResult;
+  /** Provides the plain value emitted when the matcher is serialized. */
   serialize(): T;
+  /** Optional diagnostic description; falls back to String(serialize()) when omitted. */
   toString?: () => string;
 }
 
@@ -111,7 +126,14 @@ function pathErr(message: string, path: string): MatchResult {
 /**
  * Recursively compares actual vs expected values.
  * When a MockValueMatcher is encountered in the expected tree, delegates to matcher.check().
- * Otherwise uses strict equality semantics (same as deep-equal with strict: true).
+ * Compares primitive values without coercion, arrays by length and position, Buffers
+ * by bytes, and objects by enumerable string keys and their values. Extra object keys
+ * fail; an undefined expected property can be omitted from the actual object.
+ * This is intended for payload trees, not general-purpose class or Date equality.
+ *
+ * @param path Initial diagnostic path; defaults to `$`.
+ * @param config Context forwarded to expected matchers; defaults to an empty base URL.
+ * @returns The first mismatch with its path, or a passing result. Neither tree is modified.
  */
 export function matchValues(
   actual: unknown,
 
@@ -47,11 +47,17 @@ function createDateTimeMatcher(
   });
 }
 
+/** Datetime matcher factories exposed through match.dateTime. */
 export const dateTimeMatcher = {
+  /**
+   * Matches strings with RFC 3339 syntax that parse to the same millisecond timestamp.
+   * Fractional precision and offsets may differ; a zone is optional in the accepted syntax.
+   * @throws {Error} if the expected datetime cannot be parsed.
+   */
   rfc3339(value: string): MockValueMatcher<string> {
     return createDateTimeMatcher(value, "match.dateTime.rfc3339", "rfc3339", rfc3339Pattern);
   },
-  /** Like rfc3339 but rejects timezone offsets — only Z (UTC) suffix is allowed. */
+  /** Like rfc3339 but requires a Z (UTC) suffix, rejecting offsets and missing zones. */
   utcRfc3339(value: string): MockValueMatcher<string> {
     return createDateTimeMatcher(
       value,
@@ -60,6 +66,10 @@ export const dateTimeMatcher = {
       utcRfc3339Pattern,
     );
   },
+  /**
+   * Matches HTTP-date strings ending in GMT that parse to the expected millisecond timestamp.
+   * @throws {Error} if the expected datetime cannot be parsed.
+   */
   rfc7231(value: string): MockValueMatcher<string> {
     return createDateTimeMatcher(value, "match.dateTime.rfc7231", "rfc7231", rfc7231Pattern);
   },
 
@@ -1,5 +1,9 @@
 import { createMatcher, err, type MockValueMatcher, ok } from "../match-engine.js";
 
+/**
+ * Creates the match.localUrl expectation by concatenating the runtime base URL and path.
+ * Matching requires the exact resulting string; no slash insertion or URL normalization is done.
+ */
 export function baseUrlMatcher(path: string): MockValueMatcher<string> {
   return createMatcher((config) => ({
     check(actual: unknown) {
 
@@ -1,6 +1,8 @@
 import { createMatcher, err, type MockValueMatcher, ok } from "../match-engine.js";
 
+/** String comparison factories exposed through match.string. */
 export const stringMatcher = {
+  /** Matches strings after lowercasing both values; serialization preserves the expected spelling. */
   caseInsensitive(value: string): MockValueMatcher<string> {
     const normalized = value.toLowerCase();
     return createMatcher({
 
@@ -1,22 +1,47 @@
 import { RequestExpectation } from "./expectation.js";
 import type { RequestExt } from "./types.js";
 
+/** Handler-facing view of an Express request, with assertion helpers and parsed request data. */
 export class MockRequest {
+  /** Assertions bound to the original request; failed assertions throw ValidationError. */
   public readonly expect: RequestExpectation;
 
+  /** Incoming request origin (`protocol://host`), including the port when present. */
   public readonly baseUrl: string;
-  public readonly headers: { [key: string]: string };
-  public readonly query: { [key: string]: string | string[] };
-  public readonly params: { [key: string]: string };
+  /** Parsed headers using Express/Node's lowercase names; values are not copied or normalized here. */
+  public readonly headers: {
+    /** Header value retained from the original request, without additional conversion. */
+    [key: string]: string;
+  };
+  /** Values returned by Express's query parser, including arrays for repeated parameters. */
+  public readonly query: {
+    /** One query value, or the ordered values of a repeated parameter. */
+    [key: string]: string | string[];
+  };
+  /** Named route parameters extracted by Express, shared with the original request. */
+  public readonly params: {
+    /** Route segment captured for a named parameter such as `:id`. */
+    [key: string]: string;
+  };
+  /**
+   * Payload supplied by the server's parsing middleware: parsed JSON or form values,
+   * text, or a Buffer containing raw bytes for binary payloads. Retained without conversion.
+   */
   public readonly body: any;
+  /** Multipart uploads as provided by the upload middleware; absent when no files were parsed. */
   public readonly files?:
     | {
+        /** Uploaded files associated with this form field, in middleware order. */
         [fieldname: string]: Express.Multer.File[];
       }
     | Express.Multer.File[]
     | undefined;
 
-  public constructor(public originalRequest: RequestExt) {
+  /** Wraps a request without cloning its parsed data and binds assertions to that same request. */
+  public constructor(
+    /** Underlying Express request, including rawBody for byte- or text-level assertions. */
+    public originalRequest: RequestExt,
+  ) {
     this.baseUrl = getRequestBaseUrl(originalRequest);
     this.expect = new RequestExpectation(originalRequest);
     this.headers = originalRequest.headers as { [key: string]: string };