Split up load-page functions and add docs

Author: arelra

dotcom-rendering/playwright/lib/load-page.ts

@@ -26,45 +26,83 @@ type LoadPageParams = {
 	path: string;
 } & LoadPageOptions;
 
-const getFrontendUrl = (path: string) => {
+/**
+ * @param path The path for a DCR endpoint path
+ *		e.g. `/Article/https://www.theguardian.com/world/2025/aug/19/the-big-church-move-sweden-kiruna-kyrka`
+ * @returns The Frontend URL to fetch the JSON payload
+ *		e.g. `https://www.theguardian.com/world/2025/aug/19/the-big-church-move-sweden-kiruna-kyrka.json`
+ */
+const getFrontendJsonUrl = (path: string) => {
 	const secondSlashIndex = path.indexOf('/', 1);
 	const contentUrl = path.substring(secondSlashIndex + 1);
 	return `${contentUrl}.json`;
 };
 
-const getFrontendArticle = async (
-	url: string,
+/**
+ * @param path The Frontend URL to fetch the JSON payload
+ *		e.g. `https://www.theguardian.com/world/2025/aug/19/the-big-church-move-sweden-kiruna-kyrka`
+ * @param cookies Cookies to send with the request
+ *		e.g. `GU_EDITION=US`
+ * @param queryParams Query parameters to append to the request
+ *		e.g. `live=true` for live blogs
+ * @returns The JSON response from the Frontend URL
+ */
+const getFrontendJson = async (
+	path: string,
 	cookies: Cookie[],
 	queryParams: LoadPageParams['queryParams'],
-): Promise<FEArticle | FEFront> => {
+): Promise<unknown> => {
 	try {
 		const paramsString = `${new URLSearchParams({
 			dcr: 'true',
 			...queryParams,
 		}).toString()}`;
-		const frontendUrl = `${getFrontendUrl(url)}?${paramsString}`;
+		const frontendUrl = `${getFrontendJsonUrl(path)}?${paramsString}`;
 		const cookie = cookies.map((c) => `${c.name}=${c.value}`).join('; ');
 		const response = await fetch(frontendUrl, { headers: { cookie } });
 		if (!response.ok) {
 			throw new Error(
-				`Failed to fetch article JSON from ${url}: ${response.statusText}`,
+				`Failed to fetch from ${path}: ${response.statusText}`,
 			);
 		}
-		if (url.startsWith('/Article')) {
-			return validateAsFEArticle(await response.json());
-		} else if (url.startsWith('/Front')) {
-			return validateAsFEFront(await response.json());
-		}
-		throw new Error(`Unsupported URL for fetching article: ${url}`);
+		return response.json();
 	} catch (error) {
 		throw new Error(
-			`Error fetching or validating article JSON from ${url}: ${
+			`Error fetching from ${path}: ${
 				error instanceof Error ? error.message : String(error)
 			}`,
 		);
 	}
 };
 
+/**
+ * Validates the JSON response from the Frontend URL based on the path.
+
+ * Add more validation logic here if additional content types are required.
+ *
+ * @param path The path for a DCR endpoint, used to determine the content type.
+ *		e.g. `/Article/https://www.theguardian.com/world/2025/aug/19/the-big-church-move-sweden-kiruna-kyrka`
+ * @param json The JSON response from the Frontend URL
+ * @returns The validated `FEArticle` or `FEFront` object
+ */
+const validateJson = (path: string, json: unknown): FEArticle | FEFront => {
+	if (path.startsWith('/Article')) {
+		return validateAsFEArticle(json);
+	} else if (path.startsWith('/Front')) {
+		return validateAsFEFront(json);
+	}
+	throw new Error(`Unsupported URL for validating article: ${path}`);
+};
+
+/**
+ * Constructs a DCR URL for a given path and query parameters.
+ * @param params The parameters for constructing the DCR URL
+ * @param params.path The path for a DCR endpoint
+ * @param params.queryParamsOn Whether to append query parameters to the URL
+ * @param params.queryParams Query parameters to append to the request
+ * @returns The DCR URL
+ * e.g. `http://localhost:9000/Article/https://theguardian.com/sport/live/2022/mar/27/west-indies-v-england-third-test-day-four-live?adtest=fixed-puppies-ci&live=true&force-liveblog-epic=true`
+ */
 const getDcrUrl = ({
 	path,
 	queryParamsOn,
@@ -76,10 +114,17 @@ const getDcrUrl = ({
 				...queryParams,
 		  }).toString()}`
 		: '';
-
 	return `${ORIGIN}${path}${paramsString}`;
 };
 
+/**
+ * Constructs a DCR POST URL for a given path.
+ * @param path The path for a DCR endpoint
+ *		e.g. `/Article/https://www.theguardian.com/world/2025/aug/19/the-big-church-move-sweden-kiruna-kyrka`
+ * @returns The DCR POST URL to send the request to
+ *		e.g. `http://localhost:9000/Article`
+ *		This is used to override the request method to POST in Playwright tests.
+ */
 const getDcrPostUrl = (path: string) => `${ORIGIN}/${path.split('/')[1]}`;
 
 /**
@@ -120,18 +165,21 @@ const loadPage = async ({
 	const cookies = await page.context().cookies();
 
 	// If overrides exist, but no article fixture we fetch it from Frontend
-	const frontendArticle = await (overrides.article
+	const frontendPage = await (overrides.article
 		? Promise.resolve(overrides.article)
-		: getFrontendArticle(path, cookies, queryParams));
+		: validateJson(
+				path,
+				await getFrontendJson(path, cookies, queryParams),
+		  ));
 
 	// Apply the overrides to the article config and switches
 	const postData = {
-		...frontendArticle,
+		...frontendPage,
 		config: {
-			...frontendArticle.config,
+			...frontendPage.config,
 			...overrides.configOverrides,
 			switches: {
-				...frontendArticle.config.switches,
+				...frontendPage.config.switches,
 				...overrides.switchOverrides,
 			},
 		},
@@ -143,7 +191,7 @@ const loadPage = async ({
 		queryParams,
 	});
 
-	// Override the request to the DCR URL to use a POST method
+	// Override any request matching dcrUrl to use a POST method
 	// with the overridden payload
 	await page.route(dcrUrl, async (route) => {
 		await route.continue({
@@ -157,6 +205,9 @@ const loadPage = async ({
 		});
 	});
 
+	// Initiate the page load
+	// Add the fragment here as Playwright has an issue when matching urls
+	// with fragments in the page.route handler
 	await page.goto(`${dcrUrl}${fragment ?? ''}`, { waitUntil });
 };