feat: Add baseUrl option to FetchMocker

Author: nzakas

docs/src/content/docs/fetch-mockers/mocking-browser-requests.mdx

@@ -0,0 +1,59 @@
+---
+title: Mocking Browser Requests
+description: Learn how to mock browser requests using Mentoss
+---
+
+import { Aside } from "@astrojs/starlight/components";
+
+The global `fetch()` function is available in many JavaScript runtimes, including server-side runtimes and web browsers. While `fetch()` works similarly in both environments, there are some important differences to take into account when testing code that uses `fetch()` in a browser environment. 
+
+## Relative URLs with `fetch()`
+
+Perhaps the most significant difference between using `fetch()` in a browser as opposed to a server environment is how relative URLs are handled. When you use `fetch()` in a browser, relative URLs are resolved relative to the current page's URL. This means that if you call `fetch("/api/data")` from a page at `https://example.com/page`, the request will be made to `https://example.com/api/data`. This happens automatically in the browser whenever you use `fetch()`, ensuring that requests go to the correct server.
+
+If you try to use a relative URL with `fetch()` in a server-side environment, you'll get an error. This is because the server doesn't know what the base URL should be, so it can't resolve the relative URL. That means the same `fetch()` call that works in the browser won't work in a server environment and it's important to keep that in mind when writing tests.
+
+## Mocking Browser Requests with Mentoss
+
+Mentoss provides a way to mock browser requests in your tests, allowing you to test code that uses `fetch()` without making actual network requests. To mock a browser request, you can provide a `baseUrl` option to the `FetchMocker` constructor. This option specifies the base URL that relative URLs should be resolved against. You can then call a mocked `fetch()` using a relative URL. Here's an example:
+
+```js {10, 26-27}
+import { MockServer, FetchMocker } from "mentoss";
+import { expect } from "chai";
+
+const BASE_URL = "https://api.example.com";
+
+describe("My API", () => {
+    const server = new MockServer(BASE_URL);
+    const mocker = new FetchMocker({
+        servers: [server],
+        baseUrl: BASE_URL
+    });
+
+    // extract the fetch function
+    const myFetch = mocker.fetch;
+
+    // reset the server after each test
+    afterEach(() => {
+        server.clear();
+    });
+    
+    it("should return a 200 status code", async () => {
+
+        // set up the route to test
+        server.get("/ping", 200);
+
+        // make the request
+        const response = await myFetch("/ping");
+        
+        // check the response
+        expect(response.status).to.equal(200);
+    });
+});
+```
+
+In this example, the `baseUrl` option is set to `"https://api.example.com"`, which means that relative URLs will be resolved against that base URL. The test then calls `myFetch("/ping")`, which resolves to `"https://api.example.com/ping"` and makes a request to the server. This allows you to test code that uses relative URLs with `fetch()` in a browser-like environment.
+
+<Aside type="caution">
+When using the `baseUrl` option with `FetchMocker`, make sure to set it to the correct base URL for your mock server. If you don't have a mock server defined for the base URL, the request will fail.
+</Aside>

src/fetch-mocker.js

@@ -51,6 +51,35 @@ ${traces.map(trace => {
 }).join("\n\n") || "No partial matches found."}`;
 }
 
+/**
+ * Creates a base URL from a URL or string. This is also validates
+ * the URL to ensure it's valid. Empty strings are invalid.
+ * @param {string|URL|undefined} baseUrl The base URL to create.
+ * @returns {URL|undefined} The created base URL.
+ * @throws {TypeError} When the base URL is an empty string.
+ * @throws {TypeError} When the base URL is not a string or URL.
+ */
+function createBaseUrl(baseUrl) {
+	
+	if (baseUrl === undefined) {
+		return undefined;
+	}
+	
+	if (baseUrl === "") {
+		throw new TypeError("Base URL cannot be an empty string.");
+	}
+	
+	if (baseUrl instanceof URL) {
+		return baseUrl;
+	}
+
+	if (typeof baseUrl !== "string") {
+		throw new TypeError("Base URL must be a string or URL object.");
+	}
+	
+	return new URL(baseUrl);
+}
+
 //-----------------------------------------------------------------------------
 // Exports
 //-----------------------------------------------------------------------------
@@ -76,6 +105,12 @@ export class FetchMocker {
 	 * @type {typeof Request}
 	 */
 	#Request;
+	
+	/**
+	 * The base URL to use for relative URLs.
+	 * @type {URL|undefined}
+	 */
+	#baseUrl;
 
 	/**
 	 * The global fetch function.
@@ -93,21 +128,30 @@ export class FetchMocker {
 	 * Creates a new instance.
 	 * @param {object} options Options for the instance.
 	 * @param {MockServer[]} options.servers The servers to use.
+	 * @param {string|URL} [options.baseUrl] The base URL to use for relative URLs.
 	 * @param {typeof Response} [options.CustomResponse] The Response constructor to use.
 	 * @param {typeof Request} [options.CustomRequest] The Request constructor to use.
 	 */
 	constructor({
 		servers,
+		baseUrl,
 		CustomRequest = globalThis.Request,
 		CustomResponse = globalThis.Response,
 	}) {
 		this.#servers = servers;
+		this.#baseUrl = createBaseUrl(baseUrl);
 		this.#Response = CustomResponse;
 		this.#Request = CustomRequest;
 
 		// create the function here to bind to `this`
 		this.fetch = async (input, init) => {
-			const request = new this.#Request(input, init);
+			
+			// adjust any relative URLs
+			const fixedInput = typeof input === "string" && this.#baseUrl
+				? new URL(input, this.#baseUrl).toString()
+				: input;
+			
+			const request = new this.#Request(fixedInput, init);
 			const allTraces = [];
 
 			/*

tests/fetch-mocker.test.js

@@ -332,4 +332,27 @@ describe("FetchMocker", () => {
 			assert.ok(!fetchMocker.allRoutesCalled());
 		});
 	});
+	
+	describe("Relative URLs", () => {
+		
+		it("should throw an error when using a relative URL and no baseUrl", async () => {
+			const server = new MockServer(BASE_URL);
+			const fetchMocker = new FetchMocker({ servers: [server] });
+			
+			await assert.rejects(fetchMocker.fetch("/hello"), {
+				name: "TypeError",
+				message: "Failed to parse URL from /hello",
+			});
+		});
+		
+		it("should return 200 when using a relative URL and a baseUrl", async () => {
+			const server = new MockServer(BASE_URL);
+			const fetchMocker = new FetchMocker({ servers: [server], baseUrl: BASE_URL });
+			
+			server.get("/hello", 200);
+			
+			const response = await fetchMocker.fetch("/hello");
+			assert.strictEqual(response.status, 200);
+		});
+	});
 });