{"id":"69167902adcd0bfee0251f97","title":"2025 11 04 Issue Serenity","path":"how-to/committee/release-notes/2025-11-04-issue-serenity","contentMarkdown":"# 4th November 2025 — Migration to Serenity/JS with Screenplay Pattern\n## [build 344](https://github.com/nbarrett/ngx-ramblers/actions/runs/19080934152) — [commit 34803dc](https://github.com/nbarrett/ngx-ramblers/commit/34803dc)\n\nMigrate static site migration engine from Puppeteer to Serenity/JS with Screenplay pattern, providing environment toggle and improved reliability.\n\n**Where to Find It**\n\n- **Admin → Migration**: Static site migration functionality\n- **Environment Variable**: USE_SERENITY_FOR_MIGRATION toggles between engines\n- **Local Development**: Uses bundled Chrome/Chromedriver from server directory\n\n**Benefits**\n\n- **Modern Architecture**: Actor-based Screenplay pattern for cleaner, more maintainable code\n- **Environment Flexibility**: Toggle between Puppeteer and Serenity/JS via environment variable\n- **Type-Safe Scraping**: browser.execute() provides type-safe data extraction\n- **Better Debugging**: Comprehensive debug logging in all catch blocks\n- **Docker Compatible**: Environment-specific paths for Chrome/Chromedriver\n- **Improved Error Handling**: Selector error collection and logging for failed CSS selectors\n\n**Technical Details**\n\nBackend Changes:\n- serenity-utils.ts: Browser launching with environment-specific Chrome/Chromedriver paths\n- serenity-migration-engine.ts: Actor-based navigation with browser.execute() for scraping\n- serenity-migration-utils.ts: Actor creation and Cast implementation\n- migration-routes.ts: Route handler toggles based on USE_SERENITY_FOR_MIGRATION\n- migration-types.ts: Centralized type definitions (BaseHrefResult, HtmlFetchResult, etc.)\n- environment-model.ts: Add USE_SERENITY_FOR_MIGRATION to Environment enum\n\nImplementation:\n- WebdriverIO configuration with Chrome and Chromedriver paths for local/Docker\n- Screenplay Tasks for navigation (NavigateAndWait) and content scraping\n- Navigate via Actor, scrape via type-safe browser.execute()\n- All selectors passed dynamically from config (no hard-coded selectors)\n- Remove unused PageElements and Questions (not suitable for dynamic selectors)\n\nCode Quality:\n- Export all inline types to migration-types.ts\n- Convert all Array<T> types to T[] syntax (migration and backup modules)\n- Add comprehensive debug logging to all catch blocks\n- Remove empty catch blocks throughout\n\nDev Environment:\n- Update test-setenv.sh and app-start-scripts for local Chrome/Chromedriver\n- Support Mac (Chrome for Testing.app) and Docker (Dockerfile paths)\n- Bundled Chrome/Chromedriver in server directory","contentHtml":"<h1>4th November 2025 — Migration to Serenity/JS with Screenplay Pattern</h1>\n<h2><a href=\"https://github.com/nbarrett/ngx-ramblers/actions/runs/19080934152\">build 344</a> — <a href=\"https://github.com/nbarrett/ngx-ramblers/commit/34803dc\">commit 34803dc</a></h2>\n<p>Migrate static site migration engine from Puppeteer to Serenity/JS with Screenplay pattern, providing environment toggle and improved reliability.</p>\n<p><strong>Where to Find It</strong></p>\n<ul>\n<li><strong>Admin → Migration</strong>: Static site migration functionality</li>\n<li><strong>Environment Variable</strong>: USE_SERENITY_FOR_MIGRATION toggles between engines</li>\n<li><strong>Local Development</strong>: Uses bundled Chrome/Chromedriver from server directory</li>\n</ul>\n<p><strong>Benefits</strong></p>\n<ul>\n<li><strong>Modern Architecture</strong>: Actor-based Screenplay pattern for cleaner, more maintainable code</li>\n<li><strong>Environment Flexibility</strong>: Toggle between Puppeteer and Serenity/JS via environment variable</li>\n<li><strong>Type-Safe Scraping</strong>: browser.execute() provides type-safe data extraction</li>\n<li><strong>Better Debugging</strong>: Comprehensive debug logging in all catch blocks</li>\n<li><strong>Docker Compatible</strong>: Environment-specific paths for Chrome/Chromedriver</li>\n<li><strong>Improved Error Handling</strong>: Selector error collection and logging for failed CSS selectors</li>\n</ul>\n<p><strong>Technical Details</strong></p>\n<p>Backend Changes:</p>\n<ul>\n<li>serenity-utils.ts: Browser launching with environment-specific Chrome/Chromedriver paths</li>\n<li>serenity-migration-engine.ts: Actor-based navigation with browser.execute() for scraping</li>\n<li>serenity-migration-utils.ts: Actor creation and Cast implementation</li>\n<li>migration-routes.ts: Route handler toggles based on USE_SERENITY_FOR_MIGRATION</li>\n<li>migration-types.ts: Centralized type definitions (BaseHrefResult, HtmlFetchResult, etc.)</li>\n<li>environment-model.ts: Add USE_SERENITY_FOR_MIGRATION to Environment enum</li>\n</ul>\n<p>Implementation:</p>\n<ul>\n<li>WebdriverIO configuration with Chrome and Chromedriver paths for local/Docker</li>\n<li>Screenplay Tasks for navigation (NavigateAndWait) and content scraping</li>\n<li>Navigate via Actor, scrape via type-safe browser.execute()</li>\n<li>All selectors passed dynamically from config (no hard-coded selectors)</li>\n<li>Remove unused PageElements and Questions (not suitable for dynamic selectors)</li>\n</ul>\n<p>Code Quality:</p>\n<ul>\n<li>Export all inline types to migration-types.ts</li>\n<li>Convert all Array<T> types to T[] syntax (migration and backup modules)</li>\n<li>Add comprehensive debug logging to all catch blocks</li>\n<li>Remove empty catch blocks throughout</li>\n</ul>\n<p>Dev Environment:</p>\n<ul>\n<li>Update test-setenv.sh and app-start-scripts for local Chrome/Chromedriver</li>\n<li>Support Mac (Chrome for Testing.app) and Docker (Dockerfile paths)</li>\n<li>Bundled Chrome/Chromedriver in server directory</li>\n</ul>\n"}