Add friction behaviors: chaos mode, dead clicks, form mistakes, network throttling (#25)

Author: mattpiersonMXP

index.d.ts

@@ -124,6 +124,17 @@ export interface MeepleParams {
 	sequences?: SequencesSpec | null;
 	/** Unique identifier for this simulation run */
 	runId?: string;
+
+	// ── Friction Behaviors ──
+
+	/** Simulate poor network conditions via CDP throttling */
+	networkProfile?: 'fast' | 'moderate' | 'slow3g' | 'slow4g' | 'offline';
+	/** Enable Chaos Mode: randomly sabotage POST/PUT/PATCH requests + dead clicks */
+	chaosMode?: boolean;
+	/** Probability (0-1) that a data request will fail in chaos mode. Default: 0.15 */
+	chaosFailRate?: number;
+	/** Enable intentional form mistakes: meeples submit wrong data, trigger validation, then correct */
+	formMistakes?: boolean;
 }
 
 export interface SequencesSpec {
@@ -251,6 +262,17 @@ export interface MeepleOptions {
 	sequence?: SequenceSpec;
 	/** Name of the assigned sequence */
 	sequenceName?: string;
+
+	// ── Friction Behaviors ──
+
+	/** Network throttling profile */
+	networkProfile?: 'fast' | 'moderate' | 'slow3g' | 'slow4g' | 'offline';
+	/** Enable Chaos Mode */
+	chaosMode?: boolean;
+	/** Chaos mode fail rate (0-1) */
+	chaosFailRate?: number;
+	/** Enable intentional form mistakes */
+	formMistakes?: boolean;
 }
 
 export type LogFunction = (message: string, meepleId?: string | null) => void;

meeple/browser.js

@@ -110,6 +110,96 @@ export async function launchBrowser(headless = true, log = console.log) {
 	}
 }
 
+/**
+ * Apply CDP network throttling to simulate poor network conditions
+ * @param {Page} page - Puppeteer page object
+ * @param {string} profile - Network profile: 'fast' | 'slow3g' | 'slow4g' | 'offline'
+ * @param {Function} log - Logging function
+ */
+export async function applyNetworkThrottling(page, profile = 'fast', log = console.log) {
+	if (!profile || profile === 'fast') return;
+
+	try {
+		const client = await page.createCDPSession();
+		await client.send('Network.enable');
+
+		const profiles = {
+			slow3g: {
+				offline: false,
+				downloadThroughput: ((500 * 1000) / 8) * 0.8, // 500 kbps
+				uploadThroughput: ((500 * 1000) / 8) * 0.8,
+				latency: 400 * 5 // 2000ms
+			},
+			slow4g: {
+				offline: false,
+				downloadThroughput: ((4000 * 1000) / 8) * 0.8, // 4 Mbps
+				uploadThroughput: ((3000 * 1000) / 8) * 0.8,
+				latency: 100 * 4 // 400ms
+			},
+			moderate: {
+				offline: false,
+				downloadThroughput: ((2000 * 1000) / 8) * 0.8, // 2 Mbps
+				uploadThroughput: ((1000 * 1000) / 8) * 0.8,
+				latency: 150 // 150ms
+			},
+			offline: {
+				offline: true,
+				downloadThroughput: 0,
+				uploadThroughput: 0,
+				latency: 0
+			}
+		};
+
+		const config = profiles[profile];
+		if (!config) {
+			log(`⚠️ Unknown network profile "${profile}", skipping throttling`);
+			return;
+		}
+
+		await client.send('Network.emulateNetworkConditions', config);
+		const labels = { slow3g: 'Slow 3G', slow4g: 'Slow 4G', moderate: 'Moderate (2 Mbps)', offline: 'Offline' };
+		const label = labels[profile] || profile;
+		log(`📶 <span style="color: #F8BC3B;">Network throttled to ${label}</span>`);
+	} catch (error) {
+		log(`⚠️ Network throttling failed: ${error.message}`);
+	}
+}
+
+/**
+ * Enable Chaos Mode: randomly sabotage POST/PUT/PATCH requests and intercept fetch/XHR
+ * @param {Page} page - Puppeteer page object
+ * @param {number} failRate - Probability (0-1) that a data request will be sabotaged
+ * @param {Function} log - Logging function
+ */
+export async function enableChaosMode(page, failRate = 0.15, log = console.log) {
+	try {
+		await page.setRequestInterception(true);
+		page.on('request', request => {
+			const isMixpanelRequest = request.url().includes('mixpanel') || request.url().includes('mxpnl') || request.url().includes('express-proxy-lmozz6xkha-uc.a.run.app');
+			const isDataRequest =
+				!isMixpanelRequest &&
+				['POST', 'PUT', 'PATCH'].includes(request.method()) &&
+				['xhr', 'fetch'].includes(request.resourceType());
+
+			if (isDataRequest && Math.random() < failRate) {
+				const statusCode = Math.random() < 0.5 ? 500 : 503;
+				const errorMsg = statusCode === 500 ? 'Internal Server Error' : 'Service Unavailable';
+				log(`😈 <span style="color: #CC332B;">Chaos Meeple sabotaged:</span> ${request.method()} ${request.url().substring(0, 80)}`);
+				request.respond({
+					status: statusCode,
+					contentType: 'application/json',
+					body: JSON.stringify({ error: `Simulated ${errorMsg}` })
+				});
+			} else {
+				request.continue();
+			}
+		});
+		log(`😈 <span style="color: #FF7557;">Chaos Mode enabled</span> (${(failRate * 100).toFixed(0)}% fail rate on data requests)`);
+	} catch (error) {
+		log(`⚠️ Chaos mode setup failed: ${error.message}`);
+	}
+}
+
 /**
  * Create a new page with realistic user agent and configuration
  * @param {Browser} browser - Browser instance
@@ -189,8 +279,9 @@ export async function createPage(browser, log = console.log) {
  * @param {Function} log - Logging function
  * @returns {Promise<any>} - Navigation response
  */
-export async function navigateToUrl(page, url, log = console.log) {
+export async function navigateToUrl(page, url, log = console.log, opts = {}) {
 	const maxRetries = 2;
+	const slowNetwork = opts.networkProfile && opts.networkProfile !== 'fast';
 	let lastError;
 
 	for (let attempt = 1; attempt <= maxRetries; attempt++) {
@@ -204,7 +295,7 @@ export async function navigateToUrl(page, url, log = console.log) {
 			const response = await page.goto(url, {
 				// @ts-ignore
 				waitUntil,
-				timeout: 30000 // 30 sec
+				timeout: slowNetwork ? 90000 : 30000
 			});
 
 			if (response && !response.ok()) {

meeple/forms.js

@@ -211,11 +211,111 @@ export async function fillRadioGroup(page, radioGroupElement, clicksCount = 2, l
 	}
 }
 
+/**
+ * Fill a text input with an intentional mistake, trigger validation, then correct it.
+ * Simulates real users making typos in email/URL fields and hitting validation errors.
+ * @param {Page} page - Puppeteer page object
+ * @param {ElementHandle} element - The input/textarea element
+ * @param {string} text - Correct text to ultimately type
+ * @param {Function} log - Logging function
+ * @returns {Promise<boolean>} Success status
+ */
+export async function fillTextInputWithMistake(page, element, text = null, log = console.log) {
+	try {
+		await element.scrollIntoViewIfNeeded();
+		await sleep(randomBetween(100, 300));
+
+		// Get element info to decide what kind of mistake to make
+		const elementInfo = await page.evaluate(
+			el => ({
+				type: el.type || 'text',
+				placeholder: el.placeholder || '',
+				tagName: el.tagName.toLowerCase()
+			}),
+			element
+		);
+
+		// Use provided text or select from test data
+		let correctText = text;
+		if (!correctText) {
+			const termType = ['email', 'search', 'password', 'url', 'tel', 'number'].includes(elementInfo.type)
+				? elementInfo.type
+				: 'text';
+			const availableTerms = formTestData[termType] || formTestData.text;
+			correctText = availableTerms[Math.floor(Math.random() * availableTerms.length)];
+		}
+
+		// Generate a mistake based on the field type
+		let wrongText;
+		const mistakeType = Math.random();
+
+		if (elementInfo.type === 'email' && correctText.includes('@')) {
+			// Remove the @ from an email — triggers HTML5 validation
+			wrongText = correctText.replace('@', '');
+			log(`    └─ 🤦 <span style="color: #F8BC3B;">Intentional mistake:</span> missing @ in email`);
+		} else if (elementInfo.type === 'url' && correctText.startsWith('http')) {
+			// Drop the protocol — triggers validation
+			wrongText = correctText.replace(/^https?:\/\//, '');
+			log(`    └─ 🤦 <span style="color: #F8BC3B;">Intentional mistake:</span> missing protocol in URL`);
+		} else if (elementInfo.type === 'tel') {
+			// Add letters to a phone number
+			wrongText = correctText.replace(/\d{2}/, 'ab');
+			log(`    └─ 🤦 <span style="color: #F8BC3B;">Intentional mistake:</span> letters in phone number`);
+		} else if (mistakeType < 0.5) {
+			// Truncate the text (user didn't finish typing)
+			wrongText = correctText.substring(0, Math.max(2, Math.floor(correctText.length * 0.4)));
+			log(`    └─ 🤦 <span style="color: #F8BC3B;">Intentional mistake:</span> incomplete input`);
+		} else {
+			// Swap two adjacent characters
+			const swapIdx = Math.floor(Math.random() * (correctText.length - 1));
+			wrongText =
+				correctText.substring(0, swapIdx) +
+				correctText[swapIdx + 1] +
+				correctText[swapIdx] +
+				correctText.substring(swapIdx + 2);
+			log(`    └─ 🤦 <span style="color: #F8BC3B;">Intentional mistake:</span> transposed characters`);
+		}
+
+		// Type the wrong text
+		await element.click({ clickCount: 3 });
+		await sleep(randomBetween(50, 100));
+		for (const char of wrongText) {
+			await page.keyboard.type(char);
+			await sleep(randomBetween(25, 75));
+		}
+
+		// Try to submit to trigger validation error
+		await page.keyboard.press('Enter');
+		await sleep(randomBetween(500, 1500)); // Stare at the error
+
+		// Tab away and back (another common pattern to trigger blur validation)
+		await page.keyboard.press('Tab');
+		await sleep(randomBetween(300, 800));
+
+		log(`    └─ 😤 <span style="color: #CC332B;">Validation error triggered</span> — meeple correcting...`);
+
+		// Fix it — select all and retype correctly
+		await element.click({ clickCount: 3 });
+		await sleep(randomBetween(100, 200));
+		for (const char of correctText) {
+			await page.keyboard.type(char);
+			await sleep(randomBetween(25, 75));
+		}
+
+		await sleep(randomBetween(200, 500));
+		log(`    └─ ✅ <span style="color: #07B096;">Corrected input</span>`);
+		return true;
+	} catch (error) {
+		log(`    └─ ⚠️ <span style="color: #F8BC3B;">Form mistake simulation failed:</span> ${error.message}`);
+		return false;
+	}
+}
+
 /**
  * Intelligently fill any form element based on its type
  * @param {Page} page - Puppeteer page object
  * @param {ElementHandle} element - The form element
- * @param {Object} options - Options like {text, value, clicksPerGroup}
+ * @param {Object} options - Options like {text, value, clicksPerGroup, formMistakes}
  * @param {Function} log - Logging function
  * @returns {Promise<boolean>} Success status
  */
@@ -237,6 +337,10 @@ export async function fillFormElement(page, element, options = {}, log = console
 		} else if (elementInfo.tagName === 'select') {
 			return await fillSelectDropdown(page, element, options.value, log);
 		} else if (elementInfo.tagName === 'textarea' || elementInfo.tagName === 'input') {
+			// When formMistakes is enabled, 30% chance to make an intentional mistake
+			if (options.formMistakes && Math.random() < 0.3) {
+				return await fillTextInputWithMistake(page, element, options.text, log);
+			}
 			return await fillTextInput(page, element, options.text, log);
 		}
 
@@ -250,8 +354,11 @@ export async function fillFormElement(page, element, options = {}, log = console
 /**
  * Interact with forms - search boxes, email inputs, etc.
  * ENHANCED: Now supports ALL form element types including radios and checkboxes
+ * @param {Page} page - Puppeteer page object
+ * @param {Function} log - Logging function
+ * @param {Object} [opts] - Options like { formMistakes: boolean }
  */
-export async function interactWithForms(page, log = console.log) {
+export async function interactWithForms(page, log = console.log, opts = {}) {
 	try {
 		// Check if page is still responsive
 		await page.evaluate(() => document.readyState);
@@ -386,7 +493,11 @@ export async function interactWithForms(page, log = console.log) {
 			action = `🔽 <span style="color: #9B59B6;">Select option chosen</span>`;
 		} else {
 			// Text input, textarea, or other input types
-			success = await fillTextInput(page, elementHandle, null, log);
+			if (opts.formMistakes && Math.random() < 0.3) {
+				success = await fillTextInputWithMistake(page, elementHandle, null, log);
+			} else {
+				success = await fillTextInput(page, elementHandle, null, log);
+			}
 
 			// Sometimes submit (30%), sometimes just leave it
 			if (Math.random() < 0.3) {