@fishawack/lab-env 4.43.0 → 4.44.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## Changelog
 
+### 4.44.0 (2025-08-17)
+
+#### Features
+
+* added capture webdriverio ai file ([66ef769](https://bitbucket.org/fishawackdigital/lab-env/commits/66ef7691dd48ba209d1425a27b03cd1fe20205a6))
+* enable ssh cloning via php container ([cb47b41](https://bitbucket.org/fishawackdigital/lab-env/commits/cb47b417a832d998d82f4c1e1faef0c2ab33f67f))
+
+### 4.44.0-beta.1 (2025-08-15)
+
+#### Features
+
+* added capture webdriverio ai file ([66ef769](https://bitbucket.org/fishawackdigital/lab-env/commits/66ef7691dd48ba209d1425a27b03cd1fe20205a6))
+* enable ssh cloning via php container ([cb47b41](https://bitbucket.org/fishawackdigital/lab-env/commits/cb47b417a832d998d82f4c1e1faef0c2ab33f67f))
+
 ### 4.43.0 (2025-08-10)
 
 #### Features

package/_Ai/webdriveriov9-capture.md

@@ -0,0 +1,232 @@
+---
+applyTo: "_Node/capture.js,_Node/capture-*.js,_Node/capture/**/*.js"
+---
+
+# Project Overview
+
+This project uses WebDriverIO v9 for automated screenshot capture across multiple browsers, viewport sizes, and device emulations. The capture system is designed to generate consistent visual regression testing screenshots by hooking into a test runner that iterates through configured pages and viewport configurations.
+
+The `_Node/capture.js` file serves as the entry point for custom capture logic, allowing projects to extend the default screenshot behavior with page-specific interactions, element manipulation, and additional test scenarios.
+
+## Folder Structure
+
+```
+_Node/
+├── capture.js              # Main capture customization file
+├── capture-*.js           # Additional capture files (if needed)
+└── capture/               # Capture-related modules directory
+    └── **/*.js           # Nested capture modules
+```
+
+The capture system automatically loads the first available file:
+
+1. `_Node/level-0/capture.js` (if exists)
+2. `_Node/capture.js` (fallback)
+
+## Libraries and Frameworks
+
+### WebDriverIO v9
+
+- **Browser Control**: Uses WebDriverIO's browser object for page interaction
+- **Element Selection**: Supports CSS selectors and XPath for element targeting
+- **Screenshot Capture**: Utilizes BiDi capabilities for full-page and viewport-only screenshots
+- **Device Emulation**: Supports both manual viewport sizing and device emulation profiles
+
+### Test Runner Integration
+
+- Built on a test framework using `describe()` and `it()` blocks
+- All custom interactions must be wrapped in `it()` test blocks
+- Tests run asynchronously after being mapped out synchronously
+
+## Coding Standards
+
+### Module Structure
+
+```javascript
+module.exports = {
+    // Called after viewport resize, before page iteration
+    size: (capture) => {
+        // Add dynamic pages to capture.page.array
+        // Access to capture.size properties
+    },
+
+    // Called after default page capture for each page
+    page: (capture) => {
+        // Wrap all interactions in it() blocks
+        // Access to capture.page and capture.screenshot
+    },
+};
+```
+
+### Error Handling
+
+- Let screenshot processes fail if expected selectors don't exist
+- Failing tests indicate markup changes that need attention
+- Avoid silent failures that could mask site issues
+
+### Asynchronous Operations
+
+```javascript
+// Always use async/await for browser interactions
+it("Test Description", async () => {
+    await browser.click(".selector");
+    await browser.pause(1000);
+    await capture.screenshot.call();
+});
+```
+
+### Element Waiting
+
+```javascript
+// Wait for specific elements before interaction
+await $(".selector").waitForExist(50000);
+
+// Use hard-coded waits sparingly
+await browser.pause(1000);
+```
+
+### Page-Specific Logic
+
+```javascript
+// Target specific pages using route comparison
+if (capture.page.route === "/") {
+    // Homepage-only logic
+}
+
+if (capture.page.route === "/products") {
+    // Products page logic
+}
+```
+
+## UI Guidelines
+
+### Screenshot Capture Methods
+
+#### Full Page Screenshots (Default)
+
+```javascript
+// Captures entire scrollable page content
+await capture.screenshot.call();
+// or explicitly
+await capture.screenshot.call(false);
+```
+
+#### Viewport-Only Screenshots
+
+```javascript
+// Captures only visible viewport area
+await capture.screenshot.call(true);
+```
+
+### Common UI Interaction Patterns
+
+#### Removing Overlay Elements
+
+```javascript
+it("Remove Modal Overlays", async () => {
+    await browser.execute(() => {
+        // Remove ISI trays
+        const isi = document.querySelector(".cmp-isi-tray");
+        if (isi) isi.remove();
+
+        // Remove cookie banners
+        const cookies = document.querySelector(".cookie-banner");
+        if (cookies) cookies.remove();
+
+        // Remove any modal overlays
+        const modals = document.querySelectorAll(".modal-overlay, .popup");
+        modals.forEach((modal) => modal.remove());
+    });
+});
+```
+
+#### Carousel Interaction
+
+```javascript
+it("Capture Carousel States", async () => {
+    const slides = await $$(".carousel-slide");
+
+    for (let i = 0; i < slides.length; i++) {
+        await browser.click(".carousel-next");
+        await browser.pause(500); // Allow transition
+        await capture.screenshot.call(true); // Viewport only
+    }
+});
+```
+
+#### Accordion Toggling
+
+```javascript
+it("Capture Accordion States", async () => {
+    const accordions = await $$(".accordion-header");
+
+    for (const accordion of accordions) {
+        await accordion.click();
+        await browser.pause(300); // Allow expansion
+        await capture.screenshot.call(true); // Viewport only
+    }
+});
+```
+
+#### Navigation States
+
+```javascript
+it("Navigation Menu", async () => {
+    // Open navigation
+    await browser.click(".js-menu");
+    await $(".navigation").waitForDisplayed();
+
+    // Capture viewport only to avoid scrolling
+    await capture.screenshot.call(true);
+});
+```
+
+### Dynamic Page Generation
+
+```javascript
+size: (capture) => {
+    // Add dynamic routes from router configuration
+    const dynamicRoutes = require("../_Build/js/libs/routes.js");
+
+    dynamicRoutes.forEach((route) => {
+        capture.page.array.push(route.path);
+    });
+
+    // Add programmatically generated pages
+    const productIds = ["product-1", "product-2", "product-3"];
+    productIds.forEach((id) => {
+        capture.page.array.push(`/products/${id}`);
+    });
+};
+```
+
+### Responsive Element Handling
+
+```javascript
+it("Handle Responsive Elements", async () => {
+    // Check if mobile navigation exists
+    const mobileNav = await $(".mobile-nav");
+    if (await mobileNav.isDisplayed()) {
+        await mobileNav.click();
+        await capture.screenshot.call(true);
+    }
+
+    // Check if desktop navigation exists
+    const desktopNav = await $(".desktop-nav");
+    if (await desktopNav.isDisplayed()) {
+        await desktopNav.click();
+        await capture.screenshot.call(true);
+    }
+});
+```
+
+### Best Practices
+
+- Use descriptive `it()` block names for clear test identification
+- Screenshot naming is handled automatically - don't override
+- Prefer viewport screenshots (`true`) for UI state variations
+- Use full page screenshots (`false`/omitted) for complete page captures
+- Wait for elements/animations to complete before capturing
+- Remove interfering UI elements (modals, banners) before main capture
+- Leverage `capture.page.route` for page-specific logic
+- Add dynamic pages in the `size()` method to ensure they're captured across all configurations

package/globals.js

@@ -557,18 +557,20 @@ if (!existsSync(path.join(cwd, "stylelint.config.js"))) {
     );
 }
 
+// Copy AI instructions file
+const destDir = path.join(cwd, ".github/instructions");
+if (!existsSync(destDir)) {
+    mkdirSync(destDir, { recursive: true });
+}
+
 // Copy AI instructions file
 if (
     (platform === "laravel" && process.env.VERSION_LARAVEL === "10") ||
     platform === "php"
 ) {
-    const destDir = path.join(cwd, ".github/copilot");
-    if (!existsSync(destDir)) {
-        mkdirSync(destDir, { recursive: true });
-    }
     copyFileSync(
         path.join(__dirname, "_Ai/laravel-12.md"),
-        path.join(destDir, "instructions.md"),
+        path.join(destDir, "laravel.instructions.md"),
     );
 }
 
@@ -577,16 +579,17 @@ if (
     pkg?.dependencies?.["vue"] &&
     semver.satisfies(semver.coerce(pkg.dependencies["vue"]), "3.x")
 ) {
-    const destDir = path.join(cwd, ".github/copilot");
-    if (!existsSync(destDir)) {
-        mkdirSync(destDir, { recursive: true });
-    }
     copyFileSync(
         path.join(__dirname, "_Ai/vue-3.md"),
-        path.join(destDir, "instructions.md"),
+        path.join(destDir, "vue.instructions.md"),
     );
 }
 
+copyFileSync(
+    path.join(__dirname, "_Ai/webdriveriov9-capture.md"),
+    path.join(destDir, "webdriverio-capture.instructions.md"),
+);
+
 // If docker-compose.yml exists in project _Docker folder append to end
 let localOverride = "";
 if (existsSync(path.join(cwd, "_Docker/docker-compose.yml"))) {

package/laravel/10/docker-compose.yml

@@ -36,6 +36,7 @@ services:
     volumes:
       - $CWD/:/app
       - vendor:/app/vendor
+      - $FW_DIR/.ssh:/home/php/.ssh
     environment:
       - FW_ROOT=${FW_ROOT:-}
       - USER_UID=${USER_UID:-0}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fishawack/lab-env",
-    "version": "4.43.0",
+    "version": "4.44.0",
     "description": "Docker manager for FW",
     "main": "cli.js",
     "scripts": {