✨ Add new test harness methods

Author: skerit

lib/testing/browser.js

@@ -798,5 +798,253 @@ BrowserHelper.setMethod(async function writeCoverageFiles(output_dir, prefix) {
 	return coverages.length;
 });
 
+/**
+ * Wait for the Hawkejs scene to be ready.
+ * This is important when testing pages with custom elements or client-side rendering.
+ *
+ * The scene is ready when:
+ * - The hawkejs object exists
+ * - The scene has been initialized
+ * - The general_renderer is available
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.1
+ * @version  1.4.1
+ *
+ * @param    {number}   timeout   Maximum time to wait in ms (default: 5000)
+ *
+ * @return   {Promise<boolean>}
+ */
+BrowserHelper.setMethod(async function waitForSceneReady(timeout = 5000) {
+
+	if (!this.page) {
+		throw new Error('Browser not loaded. Call load() or goto() first.');
+	}
+
+	return this.evaluate((timeout) => {
+		return new Promise((resolve) => {
+
+			const isReady = () => {
+				return typeof hawkejs !== 'undefined' &&
+				       hawkejs.scene &&
+				       hawkejs.scene.general_renderer;
+			};
+
+			if (isReady()) {
+				return resolve(true);
+			}
+
+			const start = Date.now();
+
+			const check = () => {
+				if (isReady()) {
+					return resolve(true);
+				}
+
+				if (Date.now() - start > timeout) {
+					return resolve(false);
+				}
+
+				setTimeout(check, 50);
+			};
+
+			check();
+		});
+	}, timeout);
+});
+
+/**
+ * Wait for an element to appear in the DOM using MutationObserver.
+ * This is the proper way to wait for Alchemy custom elements that render asynchronously.
+ *
+ * Unlike Puppeteer's waitForSelector, this:
+ * - Uses MutationObserver (efficient, no polling)
+ * - Returns element info, not an ElementHandle
+ * - Supports multiple selectors with "any" mode
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.1
+ * @version  1.4.1
+ *
+ * @param    {string|string[]}   selector   CSS selector(s) to wait for
+ * @param    {Object}            options
+ * @param    {number}            options.timeout   Max wait time in ms (default: 5000)
+ * @param    {boolean}           options.visible   Wait for element to be visible (default: false)
+ *
+ * @return   {Promise<Object|false>}   Element info or false if timeout
+ */
+BrowserHelper.setMethod(async function waitForElement(selector, options = {}) {
+
+	const timeout = options.timeout || 5000;
+	const visible = options.visible || false;
+
+	if (!this.page) {
+		throw new Error('Browser not loaded. Call load() or goto() first.');
+	}
+
+	const selectors = Array.isArray(selector) ? selector : [selector];
+
+	return this.evaluate((selectors, timeout, visible) => {
+		return new Promise((resolve) => {
+
+			const isVisible = (el) => {
+				if (!visible) return true;
+				const rect = el.getBoundingClientRect();
+				return rect.width > 0 && rect.height > 0;
+			};
+
+			const findElement = () => {
+				for (let selector of selectors) {
+					const el = document.querySelector(selector);
+					if (el && isVisible(el)) {
+						return el;
+					}
+				}
+				return null;
+			};
+
+			const createResult = (el) => ({
+				found: true,
+				selector: selectors.find(s => document.querySelector(s)),
+				tagName: el.tagName.toLowerCase(),
+				text: el.textContent
+			});
+
+			const found = findElement();
+			if (found) {
+				return resolve(createResult(found));
+			}
+
+			const observer = new MutationObserver(() => {
+				const el = findElement();
+				if (el) {
+					observer.disconnect();
+					resolve(createResult(el));
+				}
+			});
+
+			observer.observe(document.body, {
+				childList: true,
+				subtree: true,
+				attributes: visible
+			});
+
+			setTimeout(() => {
+				observer.disconnect();
+				const el = findElement();
+				resolve(el ? createResult(el) : false);
+			}, timeout);
+		});
+	}, selectors, timeout, visible);
+});
+
+/**
+ * Wait for all pending AJAX/fetch requests to complete.
+ * This is useful after clicking buttons that trigger API calls.
+ *
+ * Uses the browser's performance API to track pending requests.
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.1
+ * @version  1.4.1
+ *
+ * @param    {number}   timeout       Max wait time in ms (default: 5000)
+ * @param    {number}   settle_time   Time with no requests to consider settled (default: 200)
+ *
+ * @return   {Promise<boolean>}
+ */
+BrowserHelper.setMethod(async function waitForAjaxComplete(timeout = 5000, settle_time = 200) {
+
+	if (!this.page) {
+		throw new Error('Browser not loaded. Call load() or goto() first.');
+	}
+
+	return this.evaluate((timeout, settle_time) => {
+		return new Promise((resolve) => {
+			const start = Date.now();
+			let lastActivity = Date.now();
+
+			const checkSettled = () => {
+				const now = Date.now();
+
+				const entries = performance.getEntriesByType('resource');
+				const pending = entries.filter(e => {
+					return e.startTime > (performance.now() - settle_time) &&
+					       (e.initiatorType === 'fetch' || e.initiatorType === 'xmlhttprequest');
+				});
+
+				if (pending.length > 0) {
+					lastActivity = now;
+				}
+
+				if (now - lastActivity >= settle_time) {
+					return resolve(true);
+				}
+
+				if (now - start > timeout) {
+					return resolve(false);
+				}
+
+				setTimeout(checkSettled, 50);
+			};
+
+			checkSettled();
+		});
+	}, timeout, settle_time);
+});
+
+/**
+ * Wait for client-side navigation to complete.
+ * This handles both full page navigations and Hawkejs SPA-style navigations.
+ *
+ * For Hawkejs navigations, it waits for:
+ * - The scene to finish rendering
+ * - Any pending AJAX requests to settle
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.1
+ * @version  1.4.1
+ *
+ * @param    {number}   timeout   Max wait time in ms (default: 5000)
+ *
+ * @return   {Promise<boolean>}
+ */
+BrowserHelper.setMethod(async function waitForClientNavigation(timeout = 5000) {
+
+	if (!this.page) {
+		throw new Error('Browser not loaded. Call load() or goto() first.');
+	}
+
+	return this.evaluate((timeout) => {
+		return new Promise((resolve) => {
+			const start = Date.now();
+
+			const checkReady = () => {
+				const now = Date.now();
+
+				if (now - start > timeout) {
+					return resolve(false);
+				}
+
+				if (typeof hawkejs !== 'undefined' && hawkejs.scene) {
+					const renderer = hawkejs.scene.general_renderer;
+					
+					if (renderer && !renderer.rendering && document.readyState === 'complete') {
+						setTimeout(() => resolve(true), 100);
+						return;
+					}
+				} else if (document.readyState === 'complete') {
+					setTimeout(() => resolve(true), 100);
+					return;
+				}
+
+				setTimeout(checkReady, 50);
+			};
+
+			checkReady();
+		});
+	}, timeout);
+});
+
 // Export the BrowserHelper class
 module.exports = BrowserHelper;

lib/testing/harness.js

@@ -449,21 +449,31 @@ TestHarness.setMethod(function getRouteUrl(route_name, params) {
 /**
  * Make an HTTP request using Blast.fetch
  *
+ * By default on the server, Blast.fetch doesn't undry JSON-dry responses.
+ * This method sets `allow_json_dry_response: true` to mimic browser behavior,
+ * since Alchemy sends `application/json-dry` responses by default.
+ *
  * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.4.1
  * @version  1.4.1
  *
  * @param    {string}   path_or_url
  * @param    {Object}   options
  *
- * @return   {Promise<{response: Object, body: string}>}
+ * @return   {Promise<{response: Object, body: *}>}
  */
 TestHarness.setMethod(function fetch(path_or_url, options) {
 
 	if (options == null) {
 		options = {};
 	}
 
+	// Enable JSON-dry response handling (like browser does)
+	// This makes the test harness behave like a browser client
+	if (options.allow_json_dry_response == null) {
+		options.allow_json_dry_response = true;
+	}
+
 	return new Promise((resolve, reject) => {
 
 		let url;