Initial Commit

packages/testkit/testing/testing-e2e/docker/.env.example

@@ -0,0 +1,13 @@
+# Pin a specific cloakbrowser image tag (default: latest).
+# Match this to the `cloakbrowser` npm package version used in
+# packages/testing/testing-e2e to guarantee the binary matches the
+# wrapper API surface.
+CLOAKBROWSER_TAG=0.3.28
+
+# Pin the cloakbrowser-manager image tag (default: latest).
+MANAGER_TAG=latest
+
+# Set to a long random string before exposing the manager past
+# localhost. Required for the API Authorization header and the web
+# UI login screen.
+MANAGER_AUTH_TOKEN=

packages/testkit/testing/testing-e2e/docker/Dockerfile.cloakserve

@@ -0,0 +1,29 @@
+# Cloakserve image — wraps the upstream cloakhq/cloakbrowser image and
+# starts the `cloakserve` CDP multiplexer on container start. Pair
+# with @suaveplan/testing-e2e's `connectCloakServe` helper.
+#
+# Build:   docker build -f Dockerfile.cloakserve -t suaveplan-cloakserve .
+# Default upstream tag: latest. Pin via --build-arg CLOAKBROWSER_TAG=0.3.28.
+ARG CLOAKBROWSER_TAG=latest
+FROM cloakhq/cloakbrowser:${CLOAKBROWSER_TAG}
+
+# Bundle the canvas-emoji + extended font set the upstream README
+# flags as required for Kasada / Akamai (`Font Setup on Linux`).
+# The base image already has noto-color-emoji; we add the rest for
+# completeness on minimal derivatives.
+USER root
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        fonts-freefont-ttf \
+        fonts-unifont \
+        fonts-ipafont-gothic \
+        fonts-wqy-zenhei \
+        fonts-tlwg-loma-otf \
+    && rm -rf /var/lib/apt/lists/* \
+    && fc-cache -f
+
+EXPOSE 9222
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD curl -fsS http://localhost:9222/json/version || exit 1
+
+CMD ["cloakserve"]

packages/testkit/testing/testing-e2e/docker/Dockerfile.manager

@@ -0,0 +1,18 @@
+# CloakBrowser Manager image — thin wrapper around the upstream
+# cloakhq/cloakbrowser-manager image. Provides a noVNC + REST profile
+# manager (Multilogin / GoLogin / AdsPower alternative) on port 8080.
+#
+# AUTH_TOKEN: set to enable bearer-token auth on the API and a login
+# screen on the web UI. Leave unset for trusted local use only.
+#
+# Build:   docker build -f Dockerfile.manager -t suaveplan-cloakbrowser-manager .
+ARG MANAGER_TAG=latest
+FROM cloakhq/cloakbrowser-manager:${MANAGER_TAG}
+
+# Profiles persist under /data; expose so docker-compose can mount a
+# named volume.
+VOLUME ["/data"]
+
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD curl -fsS http://localhost:8080/api/status || exit 1

packages/testkit/testing/testing-e2e/docker/README.md

@@ -0,0 +1,76 @@
+# Docker bundle for `@suaveplan/testing-e2e`
+
+Two services that round-trip with `@suaveplan/testing-e2e`'s
+stealth-Chromium fixtures.
+
+## Services
+
+| Service        | Image                                | Port           | Purpose                                                                                       |
+| -------------- | ------------------------------------ | -------------- | --------------------------------------------------------------------------------------------- |
+| `cloakserve`   | `suaveplan-cloakserve:local`         | `127.0.0.1:9222` | CDP multiplexer — one container, N parallel test workers, each picking a fingerprint seed. Pair with `connectCloakServe()`. |
+| `manager`      | `suaveplan-cloakbrowser-manager:local` | `127.0.0.1:8080` | Optional noVNC + REST profile manager (Multilogin / GoLogin / AdsPower alternative). Enable via the `manager` compose profile. |
+
+Both services bind to `127.0.0.1` only. **Never expose 9222 or 8080
+to the public internet** without a reverse proxy + auth — both grant
+full browser control.
+
+## Quick start
+
+```bash
+# CDP server only — recommended for most CI / dev loops
+docker compose up -d cloakserve
+
+# + GUI profile manager (enables the `manager` compose profile)
+docker compose --profile manager up -d
+
+# Tear down
+docker compose down
+```
+
+Pin specific upstream tags via env vars:
+
+```bash
+CLOAKBROWSER_TAG=0.3.28 MANAGER_TAG=latest docker compose up -d cloakserve
+```
+
+Set an auth token on the manager before exposing past localhost:
+
+```bash
+MANAGER_AUTH_TOKEN="$(openssl rand -hex 32)" docker compose --profile manager up -d
+```
+
+## Connecting from tests
+
+```ts
+import { connectCloakServe } from "@suaveplan/testing-e2e";
+
+const browser = await connectCloakServe({
+    url: "http://localhost:9222",
+    fingerprint: 11111,
+    timezone: "America/New_York",
+    locale: "en-US",
+    proxy: process.env.RESIDENTIAL_PROXY,
+    geoip: true,
+});
+```
+
+Each unique `fingerprint` value spawns a separate Chromium process
+inside the container. Reuse the same seed across runs to look like a
+returning visitor (recommended for reCAPTCHA v3 / Enterprise scoring).
+Use `testInfo.parallelIndex` as the seed source to give each worker an
+isolated identity.
+
+## Fonts
+
+The `cloakserve` image bundles the font packages the upstream
+CloakBrowser README flags as required for Kasada / Akamai:
+
+- `fonts-noto-color-emoji` *(inherited from base)*
+- `fonts-freefont-ttf`
+- `fonts-unifont`
+- `fonts-ipafont-gothic`
+- `fonts-wqy-zenhei`
+- `fonts-tlwg-loma-otf`
+
+Without these, canvas emoji rendering hashes don't match any real
+browser and aggressive bot detection flags the session.

packages/testkit/testing/testing-e2e/docker/docker-compose.yml

@@ -0,0 +1,63 @@
+# Stealth browser stack for @suaveplan/testing-e2e.
+#
+# - `cloakserve`: stealth Chromium CDP multiplexer on 127.0.0.1:9222.
+#   Use with `connectCloakServe()` from @suaveplan/testing-e2e — one
+#   container, many parallel test workers, each seeding its own
+#   isolated Chromium identity via fingerprint query params.
+# - `cloakbrowser-manager`: optional GUI profile manager on
+#   127.0.0.1:8080. Wholly separate from `cloakserve`; spin up only
+#   when interactively curating profiles. Set AUTH_TOKEN before
+#   exposing beyond localhost.
+#
+# Usage:
+#   docker compose up -d cloakserve              # CDP server only
+#   docker compose up -d cloakserve manager      # + profile manager
+#   docker compose down                          # tear down
+#
+# Both services bind to 127.0.0.1. NEVER expose CDP (9222) or the
+# manager (8080) directly to the public internet — both grant
+# full browser control. Always front with a reverse proxy + auth.
+
+services:
+    cloakserve:
+        build:
+            context: .
+            dockerfile: Dockerfile.cloakserve
+            args:
+                CLOAKBROWSER_TAG: "${CLOAKBROWSER_TAG:-latest}"
+        image: suaveplan-cloakserve:local
+        container_name: suaveplan-cloakserve
+        restart: unless-stopped
+        ports:
+            - "127.0.0.1:9222:9222"
+        environment:
+            CLOAKBROWSER_AUTO_UPDATE: "false"
+        healthcheck:
+            test:
+                ["CMD", "curl", "-fsS", "http://localhost:9222/json/version"]
+            interval: 30s
+            timeout: 5s
+            retries: 3
+            start_period: 15s
+
+    manager:
+        build:
+            context: .
+            dockerfile: Dockerfile.manager
+            args:
+                MANAGER_TAG: "${MANAGER_TAG:-latest}"
+        image: suaveplan-cloakbrowser-manager:local
+        container_name: suaveplan-cloakbrowser-manager
+        restart: unless-stopped
+        ports:
+            - "127.0.0.1:8080:8080"
+        volumes:
+            - cloakprofiles:/data
+        environment:
+            AUTH_TOKEN: "${MANAGER_AUTH_TOKEN:-}"
+        profiles:
+            - manager
+
+volumes:
+    cloakprofiles:
+        name: suaveplan-cloakprofiles