@sudobility/testomniac_runner 0.0.128

package/plans/RUNNER.md

@@ -0,0 +1,288 @@
+# Runner Redesign Spec
+
+## Architecture
+
+1. **testomniac_runner_service** is the shared code.
+2. **testomniac_runner** is the backend worker.
+3. **testomniac_extension** is the frontend Chrome extension.
+
+- testomniac_extension is designed so developers can run local deployment in addition to dev, qa, staging, and production environments with visual feedback.
+- testomniac_runner cannot run local deployment.
+- Each run has to specify the environment (via `testEnvironmentId` FK to `test_environments`), and it has a "discovery" flag. A discovery flag indicates whether the runner should automatically find new test suite/test cases while running. If discovery is set to false, the runner should only run the tests and report results.
+- A new scan always has discovery flag set to true. It can be started on the website, which will be run by testomniac_runner. If it is started in the extension, it should be run by testomniac_extension.
+
+## Terminology
+
+**Ensure** — Find an existing record in the database. If not found, create a new one and persist it. All "ensure" operations are idempotent.
+
+**Ensure lookup keys:**
+
+- Test Suite Bundle: `(runnerId, title, uid)`
+- Test Suite: `(runnerId, title, uid)`
+- Test Case: `(testSuiteId, startingPath or action target)`
+
+## Scan Startup Flow
+
+Test case, test suite, and test suite bundle all should have a `uid` field (user firebase uid), even though the product already has an entity id. The reason is, we allow developers to run their own tests. Different environments may cause different behaviors.
+
+When a developer inputs a new URL in the extension, the developer's uid is used. If they input a new URL on the web site, the uid is not set.
+
+When starting a scan:
+
+1. Ensure a "Complete Test" test suite bundle under the runner (matching uid).
+2. Ensure a "Navigation" test suite under the runner (matching uid). Add the navigation test suite to the Complete Test bundle.
+3. In the navigation test suite, ensure a test case to navigate to the URL.
+4. Create a test suite bundle run for the Complete Test bundle.
+5. Create a test run object pointing to the test suite bundle run.
+
+In testomniac_extension, invoke the runner with the test run object.
+
+In testomniac_runner, it periodically checks if there is a test run object.
+
+Each runner should have a random UUID and a name. The runner ID is set in the run object, so we don't have multiple runners on the same run. If a test run already has a `runnerInstanceId` set, other runners skip it.
+
+## Runner Execution Logic
+
+> This replaces the existing orchestrator (`runScan`, `processDecompositionJob`, `executeTestCases`) entirely.
+
+The runner keeps track of three pointers:
+
+- **Current test suite bundle** — the bundle being executed
+- **Current test suite** — the suite being executed within the bundle
+- **Current test case** — the case being executed within the suite
+
+When the runner invokes test functions for test suite bundle, test suite, or test case, always pass in the run object and a list of expertises.
+
+### Execution loop
+
+1. Set the current test suite bundle from the run object.
+2. Pick the first open test suite in the bundle. Set it as current test suite.
+3. Pick the first open test case in the current test suite. Set it as current test case.
+4. Run the current test case (see "Running a Test Case" below).
+5. After the test case completes, search for the next open test case in the current test suite. If found, go to step 4.
+6. When all test cases in the current test suite are done, mark the test suite run as completed. Search for the next open test suite in the bundle. If found, go to step 3.
+7. When all test suites (and their test cases) in the bundle are done, mark the test suite bundle run as completed. Mark the test run as completed.
+
+Note: In discovery mode, the analyzer may add new test suites to the bundle and new test cases to suites during execution. The runner picks these up naturally because it searches for "open" items at each step.
+
+## Running a Test Case (discovery = false)
+
+Run the test case. If the test run object discovery flag is false, it uses expertises to verify the result. First, it calls the existing local decomposition (component-detector for scaffolds, pattern-detector for patterns, html-decomposer for stripping) to break down the page, and passes the following to each expertise to verify:
+
+1. Full HTML (including header meta tags)
+2. Decomposed component lists
+3. Console log during the test case run
+4. Network log during the test case run
+
+### Test Case Expectations
+
+Each test case is associated with a list of expectations.
+
+### Outcome Model
+
+In-memory outcome object:
+- `expected: string` — what was expected
+- `observed: string` — what was actually observed
+- `result: 'pass' | 'warning' | 'error'`
+
+Each expertise returns a list of outcomes.
+
+### Expertises
+
+All expertises are written fresh in `testomniac_runner_service` (not reusing the old plugin code in `testomniac_runner`). All expertises create `TestRunFinding` records in the database for both warnings and errors.
+
+1. **Tester**: Checks each test case expectation is met. If expectation is not met, creates error finding.
+2. **SEO**: Checks if the meta tags are present: title, keywords, etc. Creates findings for missing tags.
+3. **Security**: Checks if network calls contain insecure practices, such as API keys. Creates findings for violations.
+4. **Content**: No-op for now. Returns empty outcomes list.
+5. **UI**: No-op for now. Returns empty outcomes list.
+6. **Accessibility**: No-op for now. Returns empty outcomes list.
+7. **Performance**: Checks network log and makes sure all content for rendering is returned within certain time (such as 0.5 second). Creates findings for slow resources.
+
+### Setting Results
+
+With the outcomes list from each expertise, the runner sets the expected outcome and observed outcome in the test case run, and sets the status of the test case run accordingly. If test case has warnings or errors, it should have HTML, console log, and network log so the developer can get all the info needed to fix the issue.
+
+## Running a Test Case (discovery = true)
+
+If the discovery flag is set to true, we need to use other in-memory singleton objects: **Page Analyzer**.
+
+### Page Analyzer Functions
+
+1. **generateExpectations(testCase)** — Returns a list of test case expectations.
+   - It expects the result to be HTML, with no HTTP error.
+   - If the test case has just a navigation action, no more expectations.
+   - This is called **before** the expertises are called to generate outcomes. Basically, the analyzer generates a simple test expectation that the HTML loads. The tester verifies it.
+
+2. **generateTestCases(...)** — Called **after** the expertises are called and test case run's expected outcome, observed outcome, and status are set.
+
+   **Mouse-over fixup:** If the test case has only a mouse-over action, compare the current page state against the beginning page state. If they are the same (the hover had no visible effect), add a mouse click action to the test case.
+
+   **Then generate new test cases:**
+
+   When the analyzer ensures a test suite into the Complete Test bundle, it also creates a test suite run under the current bundle run. When it ensures a test case, it also creates a test case run under the corresponding test suite run. This way the execution loop finds them as "open" items immediately.
+
+   a. **Navigation test cases** — For every link detected on the page, if the current page does not require login, ensure a test case with a navigate action to that link's URL and put it into the Navigation test suite. The Navigation test suite is added to the Complete Test bundle.
+
+   b. **Scaffold test cases** — Loop through each scaffold detected on the page. For each scaffold, ensure a test suite for that scaffold. Within the scaffold, iterate through any elements that can take a mouse action. For each such element, ensure a test case with a mouse-over action targeting that element and add it to the scaffold's test suite. Add the scaffold's test suite to the Complete Test bundle.
+
+   c. **Content test cases** — Loop through the page content (non-scaffold areas). Ensure a test suite for this page. Iterate through any elements that can take a mouse action. For each such element, ensure a test case with a mouse-over action targeting that element and add it to the page's test suite. Add the page's test suite to the Complete Test bundle.
+
+## Data
+
+### Persisted Objects (Database)
+
+**Product** (existing)
+- Has an entity id (organization-level ownership)
+- Parent of runners, test suites, test suite bundles
+
+**Runner** (existing)
+- Belongs to a product
+- Represents a target application to test
+
+**Test Suite Bundle**
+- Belongs to a runner
+- `uid?: string` — firebase user id (new). Set when created by a developer in the extension; null when created from the website.
+- Contains an ordered list of test suites (via junction table)
+
+**Test Suite**
+- Belongs to a runner
+- `uid?: string` — firebase user id (new). Set when created by a developer in the extension; null when created from the website.
+- Has a starting page state and starting path
+- Has a size class, priority, suite tags
+- May be linked to a scaffold (scaffoldId, scaffoldType) or a pattern (patternType)
+- Contains test cases
+
+**Test Case**
+- Belongs to a runner and a test suite
+- `uid?: string` — firebase user id (new). Set when created by a developer in the extension; null when created from the website.
+- Has a type (render, interaction, form, navigation, e2e, password)
+- Has steps (TestStep[]), each step has an action and expectations
+- Has global expectations (Expectation[])
+- May be linked to a scaffold, pattern, page, persona, or use case
+
+**Expectation** (embedded in test case steps and global expectations)
+- `expectationType` — what to check (e.g., page_loads, element_visible, no_console_errors, etc.)
+- `expectedValue?` — the expected value
+- `severity` — 'must_pass' | 'should_pass' | 'info'
+- `description` — human-readable description
+- `playwrightCode` — code to evaluate the expectation
+
+**Test Suite Bundle Run**
+- Belongs to a test suite bundle
+- Tracks execution status of a bundle
+- Has status, startedAt, completedAt
+
+**Test Suite Run**
+- Belongs to a test suite
+- May belong to a test suite bundle run
+- Tracks execution status of a suite
+- Has status, startedAt, completedAt
+
+**Test Case Run**
+- Belongs to a test case
+- May belong to a test suite run
+- Has status, durationMs, errorMessage
+- `expectedOutcome?: string` (new) — aggregated expected outcomes from expertises
+- `observedOutcome?: string` (new) — aggregated observed outcomes from expertises
+- `screenshotPath?` — screenshot if warnings/errors
+- `consoleLog?` — console log if warnings/errors
+- `networkLog?` — network log if warnings/errors
+- Has startedAt, completedAt
+
+**Test Run**
+- Belongs to a runner
+- Points to exactly one of: test case run, test suite run, or test suite bundle run
+- `discovery: boolean` — whether to auto-discover new test suites/cases
+- `createdByUserId?` — who started the run
+- `ownedByUserId?` — who owns the run
+- `runnerInstanceId?: string` (new) — UUID of the runner instance executing this run
+- `runnerInstanceName?: string` (new) — human-readable name of the runner instance
+- Has status, scanUrl, sizeClass, stats (pagesFound, pageStatesFound, etc.)
+
+**Test Run Finding**
+- Belongs to a test case run
+- May be linked to an expertise rule
+- Has type ('error' | 'warning'), title, description
+
+**Page** (existing)
+- Belongs to a runner
+- Represents a URL path
+
+**Page State** (existing)
+- Belongs to a page
+- Represents a snapshot of the page at a point in time
+- Has HTML hashes, scaffold hash, pattern hash, screenshot, console/network logs
+
+**Scaffold** (existing)
+- Belongs to a runner
+- Detected reusable UI region (header, footer, nav, sidebar, etc.)
+- Linked to page states via junction table
+
+**Page State Pattern** (existing)
+- Belongs to a page state
+- Detected UI pattern instance (card, table, form, modal, etc.)
+
+### In-Memory Objects (Runner Service)
+
+**Outcome**
+- `expected: string` — what was expected
+- `observed: string` — what was actually observed
+- `result: 'pass' | 'warning' | 'error'`
+- Produced by expertises, consumed by the runner to set test case run results
+
+**Expertise** (interface)
+- `name: string` — expertise identifier
+- `evaluate(context: ExpertiseContext): Outcome[]` — produces outcomes
+- Implementations: Tester, SEO, Security, Content (no-op), UI (no-op), Accessibility (no-op), Performance
+
+**ExpertiseContext** (passed to each expertise)
+- `html: string` — full page HTML including head/meta tags
+- `scaffolds: DetectedScaffoldRegion[]` — decomposed scaffold list
+- `patterns: DetectedPatternWithInstances[]` — decomposed pattern list
+- `consoleLogs: string[]` — console output captured during test case execution
+- `networkLogs: NetworkLogEntry[]` — network requests/responses captured during execution
+- `expectations: Expectation[]` — the test case's expectations (used by Tester expertise)
+
+**PageAnalyzer** (singleton)
+- `generateExpectations(testCase): Expectation[]` — generates baseline expectations before expertise evaluation
+- `generateTestCases(...)` — generates new test cases for scaffolds/patterns after expertise evaluation (discovery mode only)
+
+**Runner Instance**
+- `id: string` — random UUID, generated at startup
+- `name: string` — human-readable identifier
+- Set on the test run object to claim it and prevent double-execution
+
+### Relationships
+
+```
+Product
+  └── Runner
+        ├── Test Suite Bundle ──[uid?]
+        │     └── Test Suite Bundle ↔ Test Suite (junction, ordered)
+        ├── Test Suite ──[uid?]
+        │     └── Test Case ──[uid?]
+        │           ├── TestStep[] (embedded JSON)
+        │           │     ├── TestAction
+        │           │     └── Expectation[]
+        │           └── Expectation[] (global)
+        ├── Scaffold
+        │     └── Page State ↔ Scaffold (junction)
+        └── Page
+              └── Page State
+                    └── Page State Pattern
+
+Test Suite Bundle Run ──→ Test Suite Bundle
+  └── Test Suite Run ──→ Test Suite
+        └── Test Case Run ──→ Test Case
+              └── Test Run Finding
+
+Test Run ──→ Runner
+  ├── → Test Case Run (optional)
+  ├── → Test Suite Run (optional)
+  └── → Test Suite Bundle Run (optional)
+
+Expertise ──evaluates──→ ExpertiseContext ──produces──→ Outcome[]
+PageAnalyzer ──generates──→ Expectation[] (before expertises)
+PageAnalyzer ──generates──→ Test Cases (after expertises, discovery only)
+```

package/src/adapters/PuppeteerAdapter.ts

@@ -0,0 +1,394 @@
+import type { Page } from "puppeteer-core";
+import type { BrowserAdapter } from "@sudobility/testomniac_runner_service";
+import pino from "pino";
+
+const logger = pino({ name: "puppeteer-adapter" });
+
+const REPLAY_SELECTOR_PREFIX = "tmnc-replay:";
+
+export class PuppeteerAdapter implements BrowserAdapter {
+  private page: Page;
+  private currentUrl: string = "";
+  private consoleLogBuffer: string[] = [];
+  private networkLogBuffer: Array<{
+    method: string;
+    url: string;
+    status: number;
+    contentType: string;
+  }> = [];
+
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  private async materializeSelector(selector: string): Promise<string> {
+    if (!selector.startsWith(REPLAY_SELECTOR_PREFIX)) {
+      return selector;
+    }
+
+    const token = `tmnc-replay-${Date.now()}-${Math.random()
+      .toString(36)
+      .slice(2, 8)}`;
+    return this.page.evaluate(
+      (rawSelector: string, replayToken: string, prefix: string) => {
+        const normalize = (value: string | null | undefined) =>
+          (value ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+        const isVisible = (el: Element) => {
+          if (!(el instanceof HTMLElement)) return false;
+          const rect = el.getBoundingClientRect();
+          return !el.hidden && rect.width > 0 && rect.height > 0;
+        };
+        const params = new URLSearchParams(rawSelector.slice(prefix.length));
+        const spec = {
+          css: params.get("css")?.trim() || "",
+          tagName: params.get("tagName")?.trim() || "",
+          role: params.get("role")?.trim() || "",
+          inputType: params.get("inputType")?.trim() || "",
+          accessibleName: params.get("accessibleName")?.trim() || "",
+          textContent: params.get("textContent")?.trim() || "",
+          href: params.get("href")?.trim() || "",
+          testId: params.get("testId")?.trim() || "",
+          id: params.get("id")?.trim() || "",
+          name: params.get("name")?.trim() || "",
+          placeholder: params.get("placeholder")?.trim() || "",
+        };
+        const mark = (el: Element | null) => {
+          if (!(el instanceof HTMLElement)) return rawSelector;
+          el.setAttribute("data-tmnc-replay-target", replayToken);
+          return `[data-tmnc-replay-target="${replayToken}"]`;
+        };
+
+        if (spec.css) {
+          const match = document.querySelector(spec.css);
+          if (match && isVisible(match)) return mark(match);
+        }
+
+        for (const testSelector of spec.testId
+          ? [
+              `[data-testid="${spec.testId}"]`,
+              `[data-test-id="${spec.testId}"]`,
+              `[data-test="${spec.testId}"]`,
+            ]
+          : []) {
+          const match = document.querySelector(testSelector);
+          if (match && isVisible(match)) return mark(match);
+        }
+
+        if (spec.id) {
+          const match = document.getElementById(spec.id);
+          if (match && isVisible(match)) return mark(match);
+        }
+
+        const candidates = Array.from(
+          document.querySelectorAll(spec.tagName || "*")
+        );
+        const match = candidates.find(candidate => {
+          if (!isVisible(candidate)) return false;
+          if (
+            spec.role &&
+            normalize(candidate.getAttribute("role")) !== normalize(spec.role)
+          ) {
+            const tagName = candidate.tagName.toLowerCase();
+            const roleMatchesImplicitTag =
+              (spec.role === "link" && tagName === "a") ||
+              (spec.role === "button" && tagName === "button");
+            if (!roleMatchesImplicitTag) {
+              return false;
+            }
+          }
+          if (
+            spec.inputType &&
+            normalize((candidate as HTMLInputElement).type) !==
+              normalize(spec.inputType)
+          ) {
+            return false;
+          }
+          if (
+            spec.href &&
+            normalize(candidate.getAttribute("href")) !== normalize(spec.href)
+          ) {
+            return false;
+          }
+          if (
+            spec.name &&
+            normalize(candidate.getAttribute("name")) !== normalize(spec.name)
+          ) {
+            return false;
+          }
+          if (
+            spec.placeholder &&
+            normalize(candidate.getAttribute("placeholder")) !==
+              normalize(spec.placeholder)
+          ) {
+            return false;
+          }
+
+          const candidateName = normalize(
+            candidate.getAttribute("aria-label") || candidate.textContent
+          );
+          const expectedNames = [
+            normalize(spec.accessibleName),
+            normalize(spec.textContent),
+          ].filter(Boolean);
+          return (
+            expectedNames.length === 0 ||
+            expectedNames.some(
+              expected =>
+                candidateName === expected || candidateName.includes(expected)
+            )
+          );
+        });
+
+        return mark(match ?? null);
+      },
+      selector,
+      token,
+      REPLAY_SELECTOR_PREFIX
+    );
+  }
+
+  async goto(
+    url: string,
+    options?: { waitUntil?: string; timeout?: number }
+  ): Promise<void> {
+    await this.page.goto(url, {
+      waitUntil: (options?.waitUntil as any) || "networkidle0",
+      timeout: options?.timeout || 30000,
+    });
+    this.currentUrl = this.page.url();
+  }
+
+  async click(selector: string, options?: { timeout?: number }): Promise<void> {
+    const resolvedSelector = await this.materializeSelector(selector);
+    const el = await this.page.waitForSelector(resolvedSelector, {
+      timeout: options?.timeout || 5000,
+      visible: true,
+    });
+    if (el) await el.click();
+  }
+
+  async hover(selector: string, options?: { timeout?: number }): Promise<void> {
+    const resolvedSelector = await this.materializeSelector(selector);
+    const el = await this.page.waitForSelector(resolvedSelector, {
+      timeout: options?.timeout || 5000,
+      visible: true,
+    });
+    if (el) await el.hover();
+  }
+
+  async type(selector: string, text: string): Promise<void> {
+    const resolvedSelector = await this.materializeSelector(selector);
+    const el = await this.page.waitForSelector(resolvedSelector, {
+      timeout: 5000,
+    });
+    if (el) {
+      await el.click({ clickCount: 3 });
+      await el.type(text);
+    }
+  }
+
+  async waitForSelector(
+    selector: string,
+    options?: { visible?: boolean; timeout?: number }
+  ): Promise<boolean> {
+    try {
+      const resolvedSelector = await this.materializeSelector(selector);
+      await this.page.waitForSelector(resolvedSelector, {
+        visible: options?.visible,
+        timeout: options?.timeout || 5000,
+      });
+      return true;
+    } catch (err) {
+      logger.debug({ err, selector }, "waitForSelector timeout");
+      return false;
+    }
+  }
+
+  async waitForNavigation(options?: {
+    waitUntil?: string;
+    timeout?: number;
+  }): Promise<void> {
+    try {
+      await this.page.waitForNavigation({
+        waitUntil: (options?.waitUntil as any) || "networkidle0",
+        timeout: options?.timeout || 5000,
+      });
+    } catch (err) {
+      logger.debug({ err }, "navigation timeout — may not occur");
+    }
+    this.currentUrl = this.page.url();
+  }
+
+  async evaluate<T>(
+    fn: string | ((...args: unknown[]) => T),
+    ...args: unknown[]
+  ): Promise<T> {
+    if (typeof fn === "string") {
+      return this.page.evaluate(fn) as Promise<T>;
+    }
+    return this.page.evaluate(fn, ...args) as Promise<T>;
+  }
+
+  async content(): Promise<string> {
+    return this.page.content();
+  }
+
+  url(): string {
+    return this.page.url();
+  }
+
+  async screenshot(options?: {
+    type?: string;
+    quality?: number;
+  }): Promise<Uint8Array> {
+    const buffer = await this.page.screenshot({
+      type: (options?.type as "jpeg" | "png") || "jpeg",
+      quality: options?.quality || 72,
+    });
+    return new Uint8Array(buffer);
+  }
+
+  async setViewport(width: number, height: number): Promise<void> {
+    await this.page.setViewport({ width, height });
+  }
+
+  async pressKey(key: string): Promise<void> {
+    await this.page.keyboard.press(key as any);
+  }
+
+  async select(selector: string, value: string): Promise<void> {
+    const resolvedSelector = await this.materializeSelector(selector);
+    await this.page.select(resolvedSelector, value);
+  }
+
+  async close(): Promise<void> {
+    await this.page.close();
+  }
+
+  on(
+    event: "console" | "response",
+    handler: (...args: unknown[]) => void
+  ): () => void {
+    if (event === "console") {
+      const wrapped = (msg: { type(): string; text(): string }) => {
+        const message = `${msg.type()}: ${msg.text()}`;
+        this.consoleLogBuffer.push(message);
+        handler(message);
+      };
+      this.page.on("console", wrapped as any);
+      return () => {
+        this.page.off("console", wrapped as any);
+      };
+    }
+
+    const wrapped = (response: {
+      request(): { method(): string };
+      url(): string;
+      status(): number;
+      headers(): Record<string, string>;
+    }) => {
+      const entry = {
+        method: response.request().method(),
+        url: response.url(),
+        status: response.status(),
+        contentType: response.headers()["content-type"] || "",
+        timestampMs: Date.now(),
+      };
+      this.networkLogBuffer.push(entry);
+      handler(entry);
+    };
+    this.page.on("response", wrapped as any);
+    return () => {
+      this.page.off("response", wrapped as any);
+    };
+  }
+
+  getRuntimeArtifacts() {
+    return {
+      consoleLogs: [...this.consoleLogBuffer],
+      networkLogs: [...this.networkLogBuffer],
+    };
+  }
+
+  resetRuntimeArtifacts(): void {
+    this.consoleLogBuffer = [];
+    this.networkLogBuffer = [];
+  }
+
+  async getUrl(): Promise<string> {
+    return this.page.url();
+  }
+
+  async submitTextEntry(selector: string): Promise<void> {
+    const resolvedSelector = await this.materializeSelector(selector);
+    const el = await this.page.waitForSelector(resolvedSelector, {
+      timeout: 5000,
+    });
+    if (el) {
+      await el.focus();
+      await this.page.keyboard.press("Enter");
+    }
+  }
+
+  // --- Popup / multi-tab support ---
+
+  private nextTabId = 1;
+  private pageMap = new Map<number, Page>();
+  private currentTabId = 0;
+
+  getCurrentTabId(): number {
+    if (this.currentTabId === 0) {
+      this.currentTabId = this.nextTabId++;
+      this.pageMap.set(this.currentTabId, this.page);
+    }
+    return this.currentTabId;
+  }
+
+  async waitForNewTab(timeoutMs = 10000): Promise<number | null> {
+    const browser = this.page.browser();
+    return new Promise<number | null>(resolve => {
+      let settled = false;
+      const handler = async (target: {
+        type(): string;
+        page(): Promise<Page | null>;
+      }) => {
+        if (settled) return;
+        if (target.type() !== "page") return;
+        const newPage = await target.page();
+        if (!newPage) return;
+        settled = true;
+        browser.off("targetcreated", handler as any);
+        clearTimeout(timer);
+        const id = this.nextTabId++;
+        this.pageMap.set(id, newPage);
+        resolve(id);
+      };
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        browser.off("targetcreated", handler as any);
+        resolve(null);
+      }, timeoutMs);
+      browser.on("targetcreated", handler as any);
+    });
+  }
+
+  async switchToTab(tabId: number): Promise<void> {
+    const targetPage = this.pageMap.get(tabId);
+    if (!targetPage) {
+      throw new Error(`No page found for tab ID ${tabId}`);
+    }
+    this.page = targetPage;
+    this.currentTabId = tabId;
+    this.consoleLogBuffer = [];
+    this.networkLogBuffer = [];
+    await targetPage.bringToFront();
+    this.currentUrl = this.page.url();
+    logger.info({ tabId, url: this.currentUrl }, "switchToTab");
+  }
+
+  /** Access the underlying Puppeteer Page (for scanner-specific operations) */
+  getPage(): Page {
+    return this.page;
+  }
+}

package/src/auth/credential-manager.ts

@@ -0,0 +1,17 @@
+import type { Credentials } from "@sudobility/testomniac_types";
+
+export class CredentialManager {
+  private credentials: Credentials | null = null;
+
+  setCredentials(creds: Credentials): void {
+    this.credentials = creds;
+  }
+
+  getCredentials(): Credentials | null {
+    return this.credentials;
+  }
+
+  hasCredentials(): boolean {
+    return this.credentials !== null;
+  }
+}