@zimic/interceptor 0.15.0-canary.2 → 0.15.0-canary.3

package/src/http/interceptor/types/public.ts

@@ -1,7 +1,7 @@
 import { HttpSchema } from '@zimic/http';
 
 import { SyncHttpInterceptorMethodHandler, AsyncHttpInterceptorMethodHandler } from './handlers';
-import { HttpInterceptorPlatform } from './options';
+import { HttpInterceptorPlatform, UnhandledRequestStrategy } from './options';
 
 /**
  * An interceptor to handle HTTP requests and return mock responses. The methods, paths, status codes, parameters, and
@@ -19,19 +19,37 @@ export interface HttpInterceptor<_Schema extends HttpSchema> {
    */
   baseURL: string;
 
+  /**
+   * Whether {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler request handlers}
+   * should save their intercepted requests in memory and make them accessible through
+   * {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-handlerrequests `handler.requests`}.
+   *
+   * **Important**: If `saveRequests` is true, make sure to regularly clear the interceptor to avoid that the requests
+   * accumulate in memory. A common practice is to call
+   * {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptorclear `interceptor.clear()`}
+   * after each test.
+   *
+   * @default false
+   * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#saving-requests Saving intercepted requests}
+   * @see {@link https://github.com/zimicjs/zimic/wiki/guides‐testing‐interceptor Testing}
+   */
+  saveRequests: boolean;
+
   /**
    * The platform the interceptor is running on.
    *
+   * @readonly
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptorplatform `interceptor.platform` API reference}
    */
-  platform: HttpInterceptorPlatform | null;
+  get platform(): HttpInterceptorPlatform | null;
 
   /**
    * Whether the interceptor is currently running and ready to use.
    *
+   * @readonly
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptorisrunning `interceptor.isRunning` API reference}
    */
-  isRunning: boolean;
+  get isRunning(): boolean;
 
   /**
    * Starts the interceptor, allowing it to intercept HTTP requests.
@@ -87,7 +105,7 @@ export interface HttpInterceptor<_Schema extends HttpSchema> {
    *
    * This method is useful to reset the interceptor mocks between tests.
    *
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptorclear `interceptor.clear()` API reference}
    */
   clear: (() => void) | (() => Promise<void>);
@@ -103,7 +121,17 @@ export interface HttpInterceptor<_Schema extends HttpSchema> {
  * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httpinterceptor `HttpInterceptor` API reference}
  */
 export interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInterceptor<Schema> {
-  readonly type: 'local';
+  /** @readonly */
+  get type(): 'local';
+
+  /**
+   * The strategy to use for unhandled requests. If a request starts with the base URL of the interceptor, but no
+   * matching handler exists, this strategy will be used. If a function is provided, it will be called with the
+   * unhandled request.
+   *
+   * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#unhandled-requests Unhandled requests}
+   */
+  onUnhandledRequest: UnhandledRequestStrategy.Local | undefined;
 
   /**
    * Creates a GET
@@ -126,7 +154,7 @@ export interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInt
    * @returns A GET
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   get: SyncHttpInterceptorMethodHandler<Schema, 'GET'>;
@@ -152,7 +180,7 @@ export interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInt
    * @returns A POST
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   post: SyncHttpInterceptorMethodHandler<Schema, 'POST'>;
@@ -178,7 +206,7 @@ export interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInt
    * @returns A PATCH
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   patch: SyncHttpInterceptorMethodHandler<Schema, 'PATCH'>;
@@ -204,7 +232,7 @@ export interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInt
    * @returns A PUT
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   put: SyncHttpInterceptorMethodHandler<Schema, 'PUT'>;
@@ -230,7 +258,7 @@ export interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInt
    * @returns A DELETE
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   delete: SyncHttpInterceptorMethodHandler<Schema, 'DELETE'>;
@@ -256,7 +284,7 @@ export interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInt
    * @returns A HEAD
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   head: SyncHttpInterceptorMethodHandler<Schema, 'HEAD'>;
@@ -282,7 +310,7 @@ export interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInt
    * @returns An OPTIONS
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   options: SyncHttpInterceptorMethodHandler<Schema, 'OPTIONS'>;
@@ -304,7 +332,17 @@ export interface LocalHttpInterceptor<Schema extends HttpSchema> extends HttpInt
  * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httpinterceptor `HttpInterceptor` API reference}
  */
 export interface RemoteHttpInterceptor<Schema extends HttpSchema> extends HttpInterceptor<Schema> {
-  readonly type: 'remote';
+  /** @readonly */
+  get type(): 'remote';
+
+  /**
+   * The strategy to use for unhandled requests. If a request starts with the base URL of the interceptor, but no
+   * matching handler exists, this strategy will be used. If a function is provided, it will be called with the
+   * unhandled request.
+   *
+   * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#unhandled-requests Unhandled requests}
+   */
+  onUnhandledRequest: UnhandledRequestStrategy.Remote | undefined;
 
   /**
    * Creates a GET
@@ -332,7 +370,7 @@ export interface RemoteHttpInterceptor<Schema extends HttpSchema> extends HttpIn
    * @returns A GET
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   get: AsyncHttpInterceptorMethodHandler<Schema, 'GET'>;
@@ -363,7 +401,7 @@ export interface RemoteHttpInterceptor<Schema extends HttpSchema> extends HttpIn
    * @returns A POST
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   post: AsyncHttpInterceptorMethodHandler<Schema, 'POST'>;
@@ -394,7 +432,7 @@ export interface RemoteHttpInterceptor<Schema extends HttpSchema> extends HttpIn
    * @returns A PATCH
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   patch: AsyncHttpInterceptorMethodHandler<Schema, 'PATCH'>;
@@ -425,7 +463,7 @@ export interface RemoteHttpInterceptor<Schema extends HttpSchema> extends HttpIn
    * @returns A PUT
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   put: AsyncHttpInterceptorMethodHandler<Schema, 'PUT'>;
@@ -456,7 +494,7 @@ export interface RemoteHttpInterceptor<Schema extends HttpSchema> extends HttpIn
    * @returns A DELETE
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   delete: AsyncHttpInterceptorMethodHandler<Schema, 'DELETE'>;
@@ -487,7 +525,7 @@ export interface RemoteHttpInterceptor<Schema extends HttpSchema> extends HttpIn
    * @returns A HEAD
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   head: AsyncHttpInterceptorMethodHandler<Schema, 'HEAD'>;
@@ -518,7 +556,7 @@ export interface RemoteHttpInterceptor<Schema extends HttpSchema> extends HttpIn
    * @returns An OPTIONS
    *   {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#httprequesthandler `HttpRequestHandler`}
    *   for the provided path. The path and method must be declared in the interceptor schema.
-   * @throws {NotStartedHttpInterceptorError} If the interceptor is not running.
+   * @throws {NotRunningHttpInterceptorError} If the interceptor is not running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-interceptormethodpath `interceptor.<method>(path)` API reference}
    */
   options: AsyncHttpInterceptorMethodHandler<Schema, 'OPTIONS'>;

package/src/http/interceptorWorker/LocalHttpInterceptorWorker.ts

@@ -8,7 +8,7 @@ import * as mswNode from 'msw/node';
 import { removeArrayIndex } from '@/utils/arrays';
 import { isClientSide, isServerSide } from '@/utils/environment';
 
-import NotStartedHttpInterceptorError from '../interceptor/errors/NotStartedHttpInterceptorError';
+import NotRunningHttpInterceptorError from '../interceptor/errors/NotRunningHttpInterceptorError';
 import UnknownHttpInterceptorPlatformError from '../interceptor/errors/UnknownHttpInterceptorPlatformError';
 import HttpInterceptorClient from '../interceptor/HttpInterceptorClient';
 import UnregisteredBrowserServiceWorkerError from './errors/UnregisteredBrowserServiceWorkerError';
@@ -17,8 +17,6 @@ import { LocalHttpInterceptorWorkerOptions } from './types/options';
 import { BrowserHttpWorker, HttpResponseFactory, HttpWorker, NodeHttpWorker } from './types/requests';
 
 class LocalHttpInterceptorWorker extends HttpInterceptorWorker {
-  readonly type: 'local';
-
   private internalWorker?: HttpWorker;
 
   private defaultHttpHandler: MSWHttpHandler;
@@ -28,9 +26,8 @@ class LocalHttpInterceptorWorker extends HttpInterceptorWorker {
     httpHandler: MSWHttpHandler;
   }[] = [];
 
-  constructor(options: LocalHttpInterceptorWorkerOptions) {
+  constructor(_options: LocalHttpInterceptorWorkerOptions) {
     super();
-    this.type = options.type;
 
     this.defaultHttpHandler = http.all('*', async (context) => {
       const request = context.request satisfies Request as HttpRequest;
@@ -38,9 +35,13 @@ class LocalHttpInterceptorWorker extends HttpInterceptorWorker {
     });
   }
 
+  get type() {
+    return 'local' as const;
+  }
+
   get internalWorkerOrThrow() {
     if (!this.internalWorker) {
-      throw new NotStartedHttpInterceptorError();
+      throw new NotRunningHttpInterceptorError();
     }
     return this.internalWorker;
   }

package/src/http/interceptorWorker/RemoteHttpInterceptorWorker.ts

@@ -9,7 +9,7 @@ import { deserializeRequest, serializeResponse } from '@/utils/fetch';
 import { WebSocket } from '@/webSocket/types';
 import WebSocketClient from '@/webSocket/WebSocketClient';
 
-import NotStartedHttpInterceptorError from '../interceptor/errors/NotStartedHttpInterceptorError';
+import NotRunningHttpInterceptorError from '../interceptor/errors/NotRunningHttpInterceptorError';
 import UnknownHttpInterceptorPlatformError from '../interceptor/errors/UnknownHttpInterceptorPlatformError';
 import HttpInterceptorClient, { AnyHttpInterceptorClient } from '../interceptor/HttpInterceptorClient';
 import { HttpInterceptorPlatform } from '../interceptor/types/options';
@@ -26,15 +26,12 @@ interface HttpHandler {
 }
 
 class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
-  readonly type: 'remote';
-
   webSocketClient: WebSocketClient<InterceptorServerWebSocketSchema>;
 
   private httpHandlers = new Map<HttpHandler['id'], HttpHandler>();
 
   constructor(options: RemoteHttpInterceptorWorkerOptions) {
     super();
-    this.type = options.type;
 
     const webSocketServerURL = this.deriveWebSocketServerURL(options.serverURL);
     this.webSocketClient = new WebSocketClient({
@@ -42,6 +39,10 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
     });
   }
 
+  get type() {
+    return 'remote' as const;
+  }
+
   private deriveWebSocketServerURL(serverURL: URL) {
     const webSocketServerURL = new URL(serverURL);
     webSocketServerURL.protocol = serverURL.protocol.replace(/^http(s)?:$/, 'ws$1:');
@@ -130,7 +131,7 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
     createResponse: HttpResponseFactory,
   ) {
     if (!this.isRunning) {
-      throw new NotStartedHttpInterceptorError();
+      throw new NotRunningHttpInterceptorError();
     }
 
     const crypto = await importCrypto();
@@ -164,7 +165,7 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
 
   async clearHandlers() {
     if (!this.isRunning) {
-      throw new NotStartedHttpInterceptorError();
+      throw new NotRunningHttpInterceptorError();
     }
 
     this.httpHandlers.clear();
@@ -176,7 +177,7 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
 
   async clearInterceptorHandlers<Schema extends HttpSchema>(interceptor: HttpInterceptorClient<Schema>) {
     if (!this.isRunning) {
-      throw new NotStartedHttpInterceptorError();
+      throw new NotRunningHttpInterceptorError();
     }
 
     for (const handler of this.httpHandlers.values()) {

package/src/http/requestHandler/HttpRequestHandlerClient.ts

@@ -132,7 +132,7 @@ class HttpRequestHandlerClient<
         declarationPointer: this.timesDeclarationPointer,
         unmatchedRequestGroups: this.unmatchedRequestGroups,
         hasRestrictions: this.restrictions.length > 0,
-        hasSavedRequests: this.interceptor.shouldSaveRequests,
+        hasSavedRequests: this.interceptor.saveRequests,
       });
     }
   }
@@ -168,9 +168,7 @@ class HttpRequestHandlerClient<
       this.numberOfMatchedRequests++;
     } else {
       const shouldSaveUnmatchedGroup =
-        this.interceptor.shouldSaveRequests &&
-        this.restrictions.length > 0 &&
-        this.timesDeclarationPointer !== undefined;
+        this.interceptor.saveRequests && this.restrictions.length > 0 && this.timesDeclarationPointer !== undefined;
 
       if (shouldSaveUnmatchedGroup) {
         this.unmatchedRequestGroups.push({ request, diff: restrictionsMatch.diff });
@@ -386,7 +384,7 @@ class HttpRequestHandlerClient<
     request: HttpInterceptorRequest<Path, Default<Schema[Path][Method]>>,
     response: HttpInterceptorResponse<Default<Schema[Path][Method]>, StatusCode>,
   ) {
-    const interceptedRequest = request as unknown as InterceptedHttpInterceptorRequest<
+    const interceptedRequest = request as InterceptedHttpInterceptorRequest<
       Path,
       Default<Schema[Path][Method]>,
       StatusCode
@@ -403,7 +401,7 @@ class HttpRequestHandlerClient<
   }
 
   get requests(): readonly InterceptedHttpInterceptorRequest<Path, Default<Schema[Path][Method]>, StatusCode>[] {
-    if (!this.interceptor.shouldSaveRequests) {
+    if (!this.interceptor.saveRequests) {
       throw new DisabledRequestSavingError();
     }
 

package/src/http/requestHandler/types/public.ts

@@ -32,17 +32,19 @@ export interface HttpRequestHandler<
   /**
    * The method that matches this handler.
    *
+   * @readonly
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-handlermethod `handler.method` API reference}
    */
-  method: Method;
+  get method(): Method;
 
   /**
    * The path that matches this handler. The base URL of the interceptor is not included, but it is used when matching
    * requests.
    *
+   * @readonly
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-handlerpath `handler.path` API reference}
    */
-  path: Path;
+  get path(): Path;
 }
 
 export interface InternalHttpRequestHandler<
@@ -70,7 +72,8 @@ export interface LocalHttpRequestHandler<
   Path extends HttpSchemaPath<Schema, Method>,
   StatusCode extends HttpStatusCode = never,
 > extends HttpRequestHandler<Schema, Method, Path> {
-  readonly type: 'local';
+  /** @readonly */
+  get type(): 'local';
 
   /**
    * Declares a restriction to intercepted request matches. `headers`, `searchParams`, and `body` are supported to limit
@@ -180,9 +183,10 @@ export interface LocalHttpRequestHandler<
    * for more information.
    *
    * @throws {DisabledRequestSavingError} If the interceptor was not created with `saveRequests: true`.
+   * @readonly
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-handlerrequests `handler.requests` API reference}
    */
-  requests: readonly InterceptedHttpInterceptorRequest<Path, Default<Schema[Path][Method]>, StatusCode>[];
+  get requests(): readonly InterceptedHttpInterceptorRequest<Path, Default<Schema[Path][Method]>, StatusCode>[];
 }
 
 /**
@@ -198,7 +202,8 @@ export interface SyncedRemoteHttpRequestHandler<
   Path extends HttpSchemaPath<Schema, Method>,
   StatusCode extends HttpStatusCode = never,
 > extends HttpRequestHandler<Schema, Method, Path> {
-  readonly type: 'remote';
+  /** @readonly */
+  get type(): 'remote';
 
   /**
    * Declares a restriction to intercepted request matches. `headers`, `searchParams`, and `body` are supported to limit
@@ -315,9 +320,10 @@ export interface SyncedRemoteHttpRequestHandler<
    * for more information.
    *
    * @throws {DisabledRequestSavingError} If the interceptor was not created with `saveRequests: true`.
+   * @readonly
    * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#http-handlerrequests `handler.requests` API reference}
    */
-  requests: readonly InterceptedHttpInterceptorRequest<Path, Default<Schema[Path][Method]>, StatusCode>[];
+  get requests(): readonly InterceptedHttpInterceptorRequest<Path, Default<Schema[Path][Method]>, StatusCode>[];
 }
 
 /**

package/src/server/InterceptorServer.ts

@@ -17,8 +17,10 @@ import {
   DEFAULT_ACCESS_CONTROL_HEADERS,
   DEFAULT_PREFLIGHT_STATUS_CODE,
   DEFAULT_LOG_UNHANDLED_REQUESTS,
+  DEFAULT_HOSTNAME,
 } from './constants';
-import NotStartedInterceptorServerError from './errors/NotStartedInterceptorServerError';
+import NotRunningInterceptorServerError from './errors/NotRunningInterceptorServerError';
+import RunningInterceptorServerError from './errors/RunningInterceptorServerError';
 import { InterceptorServerOptions } from './types/options';
 import { InterceptorServer as PublicInterceptorServer } from './types/public';
 import { HttpHandlerCommit, InterceptorServerWebSocketSchema } from './types/schema';
@@ -37,8 +39,8 @@ class InterceptorServer implements PublicInterceptorServer {
   private httpServer?: HttpServer;
   private webSocketServer?: WebSocketServer<InterceptorServerWebSocketSchema>;
 
-  hostname: string;
-  port: number | undefined;
+  _hostname: string;
+  _port: number | undefined;
   logUnhandledRequests: boolean;
 
   private httpHandlerGroups: {
@@ -56,16 +58,31 @@ class InterceptorServer implements PublicInterceptorServer {
   private knownWorkerSockets = new Set<Socket>();
 
   constructor(options: InterceptorServerOptions) {
-    this.hostname = options.hostname ?? 'localhost';
-    this.port = options.port;
+    this._hostname = options.hostname ?? DEFAULT_HOSTNAME;
+    this._port = options.port;
     this.logUnhandledRequests = options.logUnhandledRequests ?? DEFAULT_LOG_UNHANDLED_REQUESTS;
   }
 
-  get httpURL() {
-    if (this.port === undefined) {
-      return undefined;
+  get hostname() {
+    return this._hostname;
+  }
+
+  set hostname(newHostname: string) {
+    if (this.isRunning) {
+      throw new RunningInterceptorServerError('Did you forget to stop it before changing the hostname?');
+    }
+    this._hostname = newHostname;
+  }
+
+  get port() {
+    return this._port;
+  }
+
+  set port(newPort: number | undefined) {
+    if (this.isRunning) {
+      throw new RunningInterceptorServerError('Did you forget to stop it before changing the port?');
     }
-    return `http://${this.hostname}:${this.port}`;
+    this._port = newPort;
   }
 
   get isRunning() {
@@ -76,7 +93,7 @@ class InterceptorServer implements PublicInterceptorServer {
     /* istanbul ignore if -- @preserve
      * The HTTP server is initialized before using this method in normal conditions. */
     if (!this.httpServer) {
-      throw new NotStartedInterceptorServerError();
+      throw new NotRunningInterceptorServerError();
     }
     return this.httpServer;
   }
@@ -85,7 +102,7 @@ class InterceptorServer implements PublicInterceptorServer {
     /* istanbul ignore if -- @preserve
      * The web socket server is initialized before using this method in normal conditions. */
     if (!this.webSocketServer) {
-      throw new NotStartedInterceptorServerError();
+      throw new NotRunningInterceptorServerError();
     }
     return this.webSocketServer;
   }

package/src/server/constants.ts

@@ -28,4 +28,5 @@ export const DEFAULT_ACCESS_CONTROL_HEADERS = Object.freeze({
 /** The default status code for the preflight request. */
 export const DEFAULT_PREFLIGHT_STATUS_CODE = 204;
 
+export const DEFAULT_HOSTNAME = 'localhost';
 export const DEFAULT_LOG_UNHANDLED_REQUESTS = true;

package/src/server/errors/NotRunningInterceptorServerError.ts

@@ -0,0 +1,10 @@
+/* istanbul ignore next -- @preserve */
+/** An error thrown when the interceptor server is not running. */
+class NotRunningInterceptorServerError extends Error {
+  constructor() {
+    super('The interceptor server is not running. Did you forget to start it?');
+    this.name = 'NotRunningInterceptorServerError';
+  }
+}
+
+export default NotRunningInterceptorServerError;

package/src/server/errors/RunningInterceptorServerError.ts

@@ -0,0 +1,13 @@
+/**
+ * An error thrown when the interceptor server is running and some operation requires it to be stopped first.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐server `@zimic/interceptor/server` - API reference}
+ */
+class RunningInterceptorServerError extends Error {
+  constructor(additionalMessage: string) {
+    super(`The interceptor server is running.${additionalMessage}`);
+    this.name = 'RunningInterceptorServerError';
+  }
+}
+
+export default RunningInterceptorServerError;

package/src/server/index.ts

@@ -1,6 +1,7 @@
 import InterceptorServerNamespace from './namespace/InterceptorServerNamespace';
 
-export { default as NotStartedInterceptorServerError } from './errors/NotStartedInterceptorServerError';
+export { default as RunningInterceptorServerError } from './errors/RunningInterceptorServerError';
+export { default as NotRunningInterceptorServerError } from './errors/NotRunningInterceptorServerError';
 
 export type { InterceptorServerOptions } from './types/options';
 export type { InterceptorServer } from './types/public';

package/src/server/types/public.ts

@@ -6,15 +6,17 @@
  */
 export interface InterceptorServer {
   /**
-   * The hostname of the server.
+   * The hostname of the server. It can be reassigned to a new value if the server is not running.
    *
+   * @throws {RunningInterceptorServerError} When trying to reassign a new hostname with the server still running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐server#zimic-server `zimic-interceptor server` API reference}
    */
   hostname: string;
 
   /**
-   * The port of the server.
+   * The port of the server. It can be reassigned to a new value if the server is not running.
    *
+   * @throws {RunningInterceptorServerError} When trying to reassign a new port with the server still running.
    * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐server#zimic-server `zimic-interceptor server` API reference}
    */
   port: number | undefined;
@@ -27,19 +29,13 @@ export interface InterceptorServer {
    */
   logUnhandledRequests: boolean;
 
-  /**
-   * The HTTP URL of the server.
-   *
-   * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐server#zimic-server `zimic-interceptor server` API reference}
-   */
-  httpURL: string | undefined;
-
   /**
    * Whether the server is running.
    *
+   * @readonly
    * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐server#zimic-server `zimic-interceptor server` API reference}
    */
-  isRunning: boolean;
+  get isRunning(): boolean;
 
   /**
    * Starts the server.

package/src/webSocket/WebSocketHandler.ts

@@ -12,7 +12,7 @@ import {
 } from '@/utils/webSocket';
 
 import InvalidWebSocketMessage from './errors/InvalidWebSocketMessage';
-import NotStartedWebSocketHandlerError from './errors/NotStartedWebSocketHandlerError';
+import NotRunningWebSocketHandlerError from './errors/NotRunningWebSocketHandlerError';
 import { WebSocket } from './types';
 
 abstract class WebSocketHandler<Schema extends WebSocket.ServiceSchema> {
@@ -291,7 +291,7 @@ abstract class WebSocketHandler<Schema extends WebSocket.ServiceSchema> {
     sockets: Collection<ClientSocket> = this.sockets,
   ) {
     if (!this.isRunning) {
-      throw new NotStartedWebSocketHandlerError();
+      throw new NotRunningWebSocketHandlerError();
     }
 
     const stringifiedMessage = JSON.stringify(message);

package/src/webSocket/errors/NotRunningWebSocketHandlerError.ts

@@ -0,0 +1,8 @@
+class NotRunningWebSocketHandlerError extends Error {
+  constructor() {
+    super('Web socket handler is not running.');
+    this.name = 'NotRunningWebSocketHandlerError';
+  }
+}
+
+export default NotRunningWebSocketHandlerError;