@wdio/nightwatch-devtools 1.0.0

package/dist/index.js

@@ -0,0 +1,796 @@
+/**
+ * Nightwatch DevTools Plugin
+ *
+ * Integrates Nightwatch with WebdriverIO DevTools following the WDIO service pattern.
+ * Captures commands, network requests, and console logs during test execution in real-time.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { start, stop } from '@wdio/devtools-backend';
+import logger from '@wdio/logger';
+import { remote } from 'webdriverio';
+import { SessionCapturer } from './session.js';
+import { TestReporter } from './reporter.js';
+import { TestManager } from './helpers/testManager.js';
+import { SuiteManager } from './helpers/suiteManager.js';
+import { BrowserProxy } from './helpers/browserProxy.js';
+import { TraceType } from './types.js';
+import { determineTestState, findTestFileFromStack, deterministicUid, extractTestMetadata, parseCucumberScenario, findStepDefinitionLine, findFreePort, resolveNightwatchConfig } from './helpers/utils.js';
+import { DEFAULTS, TIMING, TEST_STATE, PLUGIN_GLOBAL_KEY } from './constants.js';
+const log = logger('@wdio/nightwatch-devtools');
+class NightwatchDevToolsPlugin {
+    options;
+    sessionCapturer;
+    testReporter;
+    testManager;
+    suiteManager;
+    browserProxy;
+    isScriptInjected = false;
+    #currentTest = null;
+    #currentScenarioSuite = null;
+    #currentStep = null;
+    #lastSessionId = null;
+    #devtoolsBrowser;
+    #userDataDir;
+    #isCucumberRunner = false;
+    #passCount = 0;
+    #failCount = 0;
+    #skipCount = 0;
+    #configPath;
+    #srcFolders = [];
+    #getRerunLabel() {
+        return process.env.DEVTOOLS_RERUN_ENTRY_TYPE === 'test'
+            ? process.env.DEVTOOLS_RERUN_LABEL?.trim()
+            : undefined;
+    }
+    constructor(options = {}) {
+        this.options = {
+            port: options.port ?? 3000,
+            hostname: options.hostname ?? 'localhost'
+        };
+    }
+    async before() {
+        // When relaunched by the DevTools UI rerun button the backend is already
+        // running — skip startup and just connect the WebSocket worker.
+        const isReuse = process.env.DEVTOOLS_APP_REUSE === '1' &&
+            process.env.DEVTOOLS_APP_HOST &&
+            process.env.DEVTOOLS_APP_PORT;
+        if (isReuse) {
+            this.options.hostname = process.env.DEVTOOLS_APP_HOST;
+            this.options.port = Number(process.env.DEVTOOLS_APP_PORT);
+            log.info(`♻  Reusing DevTools backend at ${this.options.hostname}:${this.options.port}`);
+            // Clear execution data from the previous run when rerunning
+            // This ensures test names cache and suites are fresh for the new run
+            if (this.testReporter) {
+                this.testReporter.clearExecutionData();
+                this.suiteManager.clearExecutionData();
+                // Reset counters for fresh run
+                this.#passCount = 0;
+                this.#failCount = 0;
+                this.#skipCount = 0;
+                log.info('Cleared execution data for rerun');
+            }
+        }
+        this.#configPath = resolveNightwatchConfig();
+        if (this.#configPath) {
+            log.info(`✓ Config: ${this.#configPath}`);
+        }
+        else {
+            log.warn('Could not find nightwatch config — test rerun will be unavailable');
+        }
+        if (isReuse) {
+            // Register the plugin instance so Cucumber hooks can call back into it.
+            ;
+            globalThis[PLUGIN_GLOBAL_KEY] = this;
+            return;
+        }
+        try {
+            this.options.port = await findFreePort(this.options.port, this.options.hostname);
+            log.info('🚀 Starting DevTools backend...');
+            await start(this.options);
+            const url = `http://${this.options.hostname}:${this.options.port}`;
+            log.info(`✓ Backend started on port ${this.options.port}`);
+            log.info(`  DevTools UI: ${url}`);
+            try {
+                // Create unique user data directory for this instance to prevent conflicts
+                this.#userDataDir = path.join(os.tmpdir(), `nightwatch-devtools-${this.options.port}-${Date.now()}`);
+                if (!fs.existsSync(this.#userDataDir)) {
+                    fs.mkdirSync(this.#userDataDir, { recursive: true });
+                }
+                this.#devtoolsBrowser = await remote({
+                    logLevel: 'info',
+                    automationProtocol: 'devtools',
+                    capabilities: {
+                        browserName: 'chrome',
+                        'goog:chromeOptions': {
+                            args: [
+                                '--window-size=1600,1200',
+                                `--user-data-dir=${this.#userDataDir}`,
+                                '--no-first-run',
+                                '--no-default-browser-check'
+                            ]
+                        }
+                    }
+                });
+                await this.#devtoolsBrowser.url(url);
+            }
+            catch (err) {
+                log.error(`Failed to open DevTools UI: ${err.message}`);
+                log.info(`Please manually open: ${url}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, TIMING.UI_CONNECTION_WAIT));
+            globalThis[PLUGIN_GLOBAL_KEY] = this;
+        }
+        catch (err) {
+            log.error(`Failed to start backend: ${err.message}`);
+            throw err;
+        }
+    }
+    async #ensureSessionInitialized(browser) {
+        const currentSessionId = browser.sessionId;
+        const isSessionChange = currentSessionId &&
+            this.#lastSessionId &&
+            currentSessionId !== this.#lastSessionId;
+        if (isSessionChange) {
+            log.info('Browser session changed — reconnecting WebSocket only');
+            this.isScriptInjected = false;
+            this.sessionCapturer?.cleanup();
+            this.sessionCapturer = null;
+        }
+        this.#lastSessionId = currentSessionId ?? null;
+        if (this.sessionCapturer) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, TIMING.INITIAL_CONNECTION_WAIT));
+        this.sessionCapturer = new SessionCapturer({ port: this.options.port, hostname: this.options.hostname }, browser);
+        const connected = await this.sessionCapturer.waitForConnection(3000);
+        if (!connected) {
+            log.error('❌ Worker WebSocket failed to connect!');
+        }
+        if (!this.testReporter) {
+            // First-time setup: create reporter chain once for the entire run.
+            // These must NOT be recreated on session change — doing so generates a
+            // new feature suite with a fresh start timestamp, which DataManager sees
+            // as a new run and wipes all accumulated commands.
+            this.testReporter = new TestReporter((suitesData) => {
+                if (this.sessionCapturer) {
+                    this.sessionCapturer.sendUpstream('suites', suitesData);
+                }
+            });
+            this.testManager = new TestManager(this.testReporter);
+            this.suiteManager = new SuiteManager(this.testReporter);
+            this.browserProxy = new BrowserProxy(this.sessionCapturer, this.testManager, () => this.#currentTest ?? this.#currentScenarioSuite);
+        }
+        else {
+            // Session change: update the reporter's upstream callback to use the new
+            // WebSocket, update the proxy's capturer reference (avoids re-wrapping
+            // already-wrapped browser methods which would double-capture commands),
+            // then replay current suite state to the newly-connected UI.
+            this.testReporter.updateUpstream((suitesData) => {
+                if (this.sessionCapturer) {
+                    this.sessionCapturer.sendUpstream('suites', suitesData);
+                }
+            });
+            this.browserProxy.updateSessionCapturer(this.sessionCapturer);
+            this.testReporter.updateSuites();
+        }
+        const capabilities = browser.capabilities || {};
+        const desiredCapabilities = browser.desiredCapabilities || {};
+        const sessionId = browser.sessionId;
+        const opts = browser.options || {};
+        // Capture src_folders once so beforeEach can resolve test file paths
+        if (this.#srcFolders.length === 0) {
+            const sf = opts.src_folders;
+            this.#srcFolders = Array.isArray(sf) ? sf : sf ? [sf] : [];
+        }
+        this.sessionCapturer.sendUpstream('metadata', {
+            type: TraceType.Testrunner,
+            capabilities,
+            desiredCapabilities,
+            sessionId,
+            testEnv: opts.testEnv,
+            host: opts.webdriver?.host,
+            options: this.#buildMetadataOptions(),
+            url: ''
+        });
+        const browserName = capabilities.browserName || desiredCapabilities.browserName || 'unknown';
+        const browserVersion = capabilities.browserVersion || capabilities.version || '';
+        log.info(`✓ Browser: ${browserName}${browserVersion ? ' ' + browserVersion : ''} (session: ${sessionId})`);
+        const loggingPrefs = capabilities['goog:loggingPrefs'] ||
+            desiredCapabilities['goog:loggingPrefs'] ||
+            {};
+        if (!loggingPrefs.performance) {
+            log.warn("⚠  Network tab will be empty — add 'goog:loggingPrefs': { performance: 'ALL' } to your capabilities");
+        }
+    }
+    async cucumberBefore(browser, pickle) {
+        this.#isCucumberRunner = true;
+        await this.#initCucumberScenario(browser, pickle);
+    }
+    async cucumberAfter(browser, result, pickle) {
+        await this.#finalizeCucumberScenario(browser, result, pickle);
+    }
+    /** Called from Cucumber Before hook (order:1000) — one call per scenario. */
+    async #initCucumberScenario(browser, pickle) {
+        await this.#ensureSessionInitialized(browser);
+        const featureUri = pickle.uri ?? 'unknown.feature';
+        const scenarioName = pickle.name ?? 'Unknown Scenario';
+        // Derive the feature name from the "Feature: <name>" header in the file,
+        // falling back to the filename (e.g. "login") only if the file can't be read.
+        let featureName = path.basename(featureUri, '.feature');
+        let featureContent = '';
+        const featureAbsPath = path.resolve(process.cwd(), featureUri);
+        const stepDefFiles = [];
+        if (featureUri !== 'unknown.feature' && fs.existsSync(featureAbsPath)) {
+            featureContent = fs.readFileSync(featureAbsPath, 'utf-8');
+            const match = featureContent.match(/^\s*Feature:\s*(.+)/m);
+            if (match) {
+                featureName = match[1].trim();
+            }
+            this.sessionCapturer.captureSource(featureAbsPath).catch(() => { });
+            // Capture step definitions from sibling directories
+            const featureDir = path.dirname(featureAbsPath);
+            const stepDirCandidates = ['step_definitions', 'steps', 'support'];
+            for (const candidate of stepDirCandidates) {
+                const stepDir = path.join(featureDir, candidate);
+                if (fs.existsSync(stepDir) && fs.statSync(stepDir).isDirectory()) {
+                    for (const entry of fs.readdirSync(stepDir)) {
+                        if (/\.(js|ts|mjs|cjs)$/.test(entry)) {
+                            const stepFilePath = path.join(stepDir, entry);
+                            this.sessionCapturer.captureSource(stepFilePath).catch(() => { });
+                            try {
+                                stepDefFiles.push({
+                                    filePath: stepFilePath,
+                                    content: fs.readFileSync(stepFilePath, 'utf-8')
+                                });
+                            }
+                            catch {
+                                // skip unreadable files
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // Get or create the feature-level suite (no individual test names — scenarios go into suites[])
+        const featureSuite = this.suiteManager.getOrCreateSuite(featureUri, featureName, featureUri, []);
+        this.suiteManager.markSuiteAsRunning(featureSuite);
+        // Parse step keywords from the feature file
+        const steps = pickle.steps ?? [];
+        // Parse line numbers and keywords for TestLens navigation and step labels
+        const { featureLine, scenarioLine, stepLines, stepKeywords } = parseCucumberScenario(featureContent, scenarioName, steps.map((s) => s.text));
+        if (featureAbsPath && featureLine > 0) {
+            featureSuite.callSource = `${featureAbsPath}:${featureLine}`;
+        }
+        // Create a scenario sub-suite (child of feature suite).
+        // Use deterministicUid (no counter) so the SAME scenario always maps to the
+        // SAME uid across retries, enabling correct retry detection below.
+        const scenarioUid = deterministicUid(featureUri, `scenario:${scenarioName}`);
+        const scenarioSuite = {
+            uid: scenarioUid,
+            cid: DEFAULTS.CID,
+            title: scenarioName,
+            fullTitle: `${featureName} ${scenarioName}`,
+            parent: featureSuite.uid,
+            type: 'suite',
+            file: featureUri,
+            start: new Date(),
+            state: 'running',
+            end: null,
+            tests: [],
+            suites: [],
+            hooks: [],
+            _duration: 0,
+            callSource: featureAbsPath && scenarioLine > 0
+                ? `${featureAbsPath}:${scenarioLine}`
+                : undefined
+        };
+        // Create a TestStats entry for each step
+        steps.forEach((step, i) => {
+            const keyword = stepKeywords[i] || '';
+            const stepLabel = keyword ? `${keyword} ${step.text}` : step.text;
+            const stepUid = deterministicUid(featureUri, `step:${scenarioName}:${step.text}`);
+            scenarioSuite.tests.push({
+                uid: stepUid,
+                cid: DEFAULTS.CID,
+                title: stepLabel,
+                fullTitle: `${scenarioName} ${stepLabel}`,
+                parent: scenarioUid,
+                state: 'pending',
+                start: new Date(),
+                end: null,
+                type: 'test',
+                file: featureUri,
+                retries: 0,
+                _duration: 0,
+                hooks: [],
+                callSource: (() => {
+                    const loc = findStepDefinitionLine(stepDefFiles, step.text);
+                    if (loc) {
+                        return `${loc.filePath}:${loc.line}`;
+                    }
+                    if (featureAbsPath && stepLines[i] > 0) {
+                        return `${featureAbsPath}:${stepLines[i]}`;
+                    }
+                    return undefined;
+                })()
+            });
+        });
+        // Add scenario sub-suite to the feature suite.
+        // If a suite with this uid already exists it means this is a RETRY of the same
+        // scenario — clear execution data so only the latest attempt's commands are shown.
+        const existingIdx = featureSuite.suites.findIndex((s) => s.uid === scenarioUid);
+        const isRetry = existingIdx !== -1;
+        if (isRetry) {
+            featureSuite.suites[existingIdx] = scenarioSuite;
+            // Pass the specific scenario uid so only this scenario's execution data
+            // is reset — a uid-less clearExecutionData would mark ALL suites as
+            // running, destroying the previous terminal states of sibling scenarios.
+            this.sessionCapturer.sendUpstream('clearExecutionData', {
+                uid: scenarioUid,
+                entryType: 'suite'
+            });
+        }
+        else {
+            featureSuite.suites.push(scenarioSuite);
+        }
+        this.#currentScenarioSuite = scenarioSuite;
+        this.#currentStep = null;
+        this.#currentTest = null;
+        this.testReporter.updateSuites();
+        if (!this.isScriptInjected) {
+            this.browserProxy.wrapUrlMethod(browser);
+            this.isScriptInjected = true;
+        }
+        this.browserProxy.wrapBrowserCommands(browser);
+        this.browserProxy.resetCommandTracking();
+        log.info(`🥒 Scenario: ${scenarioName}`);
+    }
+    /** Called from Cucumber After hook (order:1000) — one call per scenario. */
+    async #finalizeCucumberScenario(browser, result, pickle) {
+        try {
+            const status = String(result?.status ?? 'UNKNOWN').toUpperCase();
+            const scenarioState = status === 'PASSED'
+                ? TEST_STATE.PASSED
+                : status === 'SKIPPED'
+                    ? TEST_STATE.SKIPPED
+                    : TEST_STATE.FAILED;
+            if (this.#currentScenarioSuite) {
+                const duration = Date.now() -
+                    (this.#currentScenarioSuite.start?.getTime() ?? Date.now());
+                this.#currentScenarioSuite.state = scenarioState;
+                this.#currentScenarioSuite.end = new Date();
+                this.#currentScenarioSuite._duration = duration;
+                // Ensure any still-running or pending steps are marked appropriately
+                for (const step of this.#currentScenarioSuite.tests) {
+                    if (typeof step !== 'string' &&
+                        (step.state === 'running' || step.state === 'pending')) {
+                        step.state =
+                            scenarioState === TEST_STATE.PASSED
+                                ? TEST_STATE.PASSED
+                                : TEST_STATE.FAILED;
+                        step.end = new Date();
+                    }
+                }
+                const featureUri = pickle?.uri ?? 'unknown.feature';
+                this.testManager.markTestAsProcessed(featureUri, pickle?.name ?? '');
+                const featureSuite = this.suiteManager.getSuite(featureUri);
+                if (featureSuite) {
+                    // Finalize is not called until all scenarios are done — just update state
+                    this.suiteManager.finalizeSuiteState(featureSuite);
+                }
+                this.#incrementCount(scenarioState);
+                const icon = this.#testIcon(scenarioState);
+                const durationSec = (duration / 1000).toFixed(2);
+                log.info(`  ${icon} ${pickle?.name ?? 'Unknown'} (${durationSec}s)`);
+                this.testReporter.updateSuites();
+                this.#currentScenarioSuite = null;
+                this.#currentStep = null;
+                this.#currentTest = null;
+            }
+            await this.sessionCapturer.captureTrace(browser);
+        }
+        catch (err) {
+            log.error(`Failed to finalize Cucumber scenario: ${err.message}`);
+        }
+    }
+    /** Called from Cucumber BeforeStep hook — marks the step as running. */
+    async cucumberBeforeStep(browser, pickleStep, _pickle) {
+        if (!this.#currentScenarioSuite) {
+            return;
+        }
+        // Reset per-step dedup tracking so commands in step N are never
+        // mistaken for retries of identically-signatured commands from step N-1.
+        this.browserProxy?.resetCommandTracking();
+        const stepText = pickleStep?.text ?? '';
+        const step = this.#currentScenarioSuite.tests.find((t) => typeof t !== 'string' &&
+            (t.title.endsWith(stepText) || t.title === stepText));
+        if (step) {
+            step.state = TEST_STATE.RUNNING;
+            step.start = new Date();
+            step.end = null;
+            this.#currentStep = step;
+            this.testReporter.updateSuites();
+        }
+    }
+    /** Called from Cucumber AfterStep hook — records the step result. */
+    async cucumberAfterStep(_browser, result, pickleStep, _pickle) {
+        const step = this.#currentStep;
+        if (!step) {
+            return;
+        }
+        const status = String(result?.status ?? 'UNKNOWN').toUpperCase();
+        const stepState = status === 'PASSED'
+            ? TEST_STATE.PASSED
+            : status === 'SKIPPED'
+                ? TEST_STATE.SKIPPED
+                : TEST_STATE.FAILED;
+        step.state = stepState;
+        step.end = new Date();
+        step._duration = Date.now() - (step.start?.getTime() ?? Date.now());
+        this.#currentStep = null;
+        this.testReporter.updateSuites();
+        void pickleStep; // used by BeforeStep to find the step
+    }
+    async beforeEach(browser) {
+        if (this.#isCucumberRunner) {
+            return;
+        }
+        await this.#ensureSessionInitialized(browser);
+        const currentTest = browser.currentTest;
+        if (!currentTest) {
+            return;
+        }
+        const testFile = (currentTest.module || '').split('/').pop() ||
+            currentTest.module ||
+            DEFAULTS.FILE_NAME;
+        let fullPath = findTestFileFromStack() || null;
+        const cachedPath = this.browserProxy.getCurrentTestFullPath();
+        if (!fullPath && cachedPath && cachedPath.includes(testFile)) {
+            fullPath = cachedPath;
+        }
+        if (!fullPath && testFile) {
+            const workspaceRoot = process.cwd();
+            // currentTest.module is the path relative to a src_folder, e.g. "basic/ecosia"
+            // So we must try: path.join(cwd, srcFolder, module + '.js') for each src_folder
+            const modulePath = (currentTest.module || '').replace(/\\/g, '/');
+            const srcFolderPaths = this.#srcFolders.flatMap((sf) => modulePath
+                ? [
+                    path.join(workspaceRoot, sf, modulePath + '.js'),
+                    path.join(workspaceRoot, sf, modulePath + '.ts'),
+                    path.join(workspaceRoot, sf, modulePath + '.cjs'),
+                    path.join(workspaceRoot, sf, modulePath)
+                ]
+                : []);
+            const possiblePaths = [
+                // Highest priority: expand module path via each configured src_folder
+                ...srcFolderPaths,
+                // Fallback: treat module path as relative to cwd (works when src_folders isn't nested)
+                ...(modulePath
+                    ? [
+                        path.join(workspaceRoot, modulePath + '.js'),
+                        path.join(workspaceRoot, modulePath + '.ts'),
+                        path.join(workspaceRoot, modulePath + '.cjs'),
+                        path.join(workspaceRoot, modulePath)
+                    ]
+                    : []),
+                path.join(workspaceRoot, 'example/tests', testFile + '.js'),
+                path.join(workspaceRoot, 'example/tests', testFile),
+                path.join(workspaceRoot, 'tests', testFile + '.js'),
+                path.join(workspaceRoot, 'test', testFile + '.js'),
+                path.join(workspaceRoot, testFile + '.js')
+            ];
+            for (const possiblePath of possiblePaths) {
+                if (fs.existsSync(possiblePath)) {
+                    fullPath = possiblePath;
+                    break;
+                }
+            }
+        }
+        // Extract suite title and test metadata
+        let suiteTitle = testFile;
+        if (!fullPath) {
+            log.warn(`[beforeEach] Could not resolve file path for "${testFile}" — source view will be unavailable`);
+        }
+        let testNames = [];
+        let suiteLine = null;
+        let testLines = [];
+        if (fullPath) {
+            const { suiteTitle: parsedTitle, testNames: parsedNames, suiteLine: parsedSuiteLine, testLines: parsedTestLines } = extractTestMetadata(fullPath);
+            if (parsedTitle) {
+                suiteTitle = parsedTitle;
+            }
+            testNames = parsedNames;
+            suiteLine = parsedSuiteLine;
+            testLines = parsedTestLines;
+        }
+        const rerunLabel = this.#getRerunLabel();
+        if (rerunLabel) {
+            const targetIndex = testNames.findIndex((name) => name === rerunLabel);
+            if (targetIndex !== -1) {
+                testNames = [testNames[targetIndex]];
+                testLines = testLines[targetIndex] ? [testLines[targetIndex]] : [];
+            }
+        }
+        // Get or create suite for this test file
+        const currentSuite = this.suiteManager.getOrCreateSuite(testFile, suiteTitle, fullPath, testNames, suiteLine, testLines);
+        // Capture source file for display
+        if (fullPath && fullPath.includes('/')) {
+            this.sessionCapturer.captureSource(fullPath).catch(() => { });
+        }
+        const runningTest = currentSuite.tests.find((t) => typeof t !== 'string' && t.state === TEST_STATE.RUNNING);
+        if (runningTest) {
+            const testcases = currentTest?.results?.testcases || {};
+            if (testcases[runningTest.title]) {
+                const testcase = testcases[runningTest.title];
+                const testState = determineTestState(testcase);
+                runningTest.state = testState;
+                runningTest.end = new Date();
+                runningTest._duration = parseFloat(testcase.time || '0') * 1000;
+                this.testManager.updateTestState(runningTest, testState);
+                this.testManager.markTestAsProcessed(testFile, runningTest.title);
+                this.#incrementCount(testState);
+                const prevIcon = this.#testIcon(testState);
+                log.info(`  ${prevIcon} ${runningTest.title} (${(runningTest._duration / 1000).toFixed(2)}s)`);
+            }
+            else {
+                const endTime = new Date();
+                const duration = endTime.getTime() - (runningTest.start?.getTime() || 0);
+                this.testManager.updateTestState(runningTest, TEST_STATE.PASSED, endTime, duration);
+                this.testManager.markTestAsProcessed(testFile, runningTest.title);
+                this.#passCount++;
+                log.info(`  ✅ ${runningTest.title} (${(duration / 1000).toFixed(2)}s)`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, TIMING.UI_RENDER_DELAY));
+        }
+        const processedTests = this.testManager.getProcessedTests(testFile);
+        const runtimeTestName = typeof currentTest?.name === 'string'
+            ? currentTest.name.trim()
+            : undefined;
+        const matchedRuntimeTestName = runtimeTestName
+            ? testNames.find((name) => runtimeTestName === name || runtimeTestName.endsWith(` ${name}`))
+            : undefined;
+        const currentTestName = matchedRuntimeTestName ||
+            testNames.find((name) => !processedTests.has(name));
+        if (currentTestName) {
+            if (processedTests.size === 0) {
+                this.suiteManager.markSuiteAsRunning(currentSuite);
+            }
+            const test = this.testManager.findTestInSuite(currentSuite, currentTestName);
+            if (test) {
+                test.state = TEST_STATE.RUNNING;
+                test.start = new Date();
+                test.end = null;
+                this.testReporter.onTestStart(test);
+                this.#currentTest = test;
+                log.info(`  ▶ ${currentTestName}`);
+                await new Promise((resolve) => setTimeout(resolve, TIMING.TEST_START_DELAY));
+            }
+            else {
+                log.warn(`Test "${currentTestName}" not found in suite "${currentSuite.title}"`);
+                this.#currentTest = null;
+            }
+        }
+        if (!this.isScriptInjected) {
+            this.browserProxy.wrapUrlMethod(browser);
+            this.isScriptInjected = true;
+        }
+        this.browserProxy.resetCommandTracking();
+        this.browserProxy.wrapBrowserCommands(browser);
+    }
+    async afterEach(browser) {
+        // Cucumber runner manages its own lifecycle via cucumberHooks.cjs
+        if (this.#isCucumberRunner) {
+            return;
+        }
+        if (browser && this.sessionCapturer) {
+            try {
+                const currentTest = browser.currentTest;
+                const results = currentTest?.results || {};
+                const testFile = (currentTest.module || '').split('/').pop() || DEFAULTS.FILE_NAME;
+                const testcases = results.testcases || {};
+                const testcaseNames = Object.keys(testcases);
+                const currentSuite = this.suiteManager.getSuite(testFile);
+                if (currentSuite) {
+                    const processedTests = this.testManager.getProcessedTests(testFile);
+                    if (testcaseNames.length === 0) {
+                        const runningTest = currentSuite.tests.find((t) => typeof t !== 'string' && t.state === TEST_STATE.RUNNING);
+                        if (runningTest && !processedTests.has(runningTest.title)) {
+                            const testState = results.errors > 0 || results.failed > 0
+                                ? TEST_STATE.FAILED
+                                : TEST_STATE.PASSED;
+                            const endTime = new Date();
+                            const duration = endTime.getTime() - (runningTest.start?.getTime() || 0);
+                            this.testManager.updateTestState(runningTest, testState, endTime, duration);
+                            this.testManager.markTestAsProcessed(testFile, runningTest.title);
+                            this.#incrementCount(testState);
+                            const icon = this.#testIcon(testState);
+                            log.info(`  ${icon} ${runningTest.title} (${(duration / 1000).toFixed(2)}s)`);
+                        }
+                    }
+                    else {
+                        const unprocessedTests = testcaseNames.filter((name) => !processedTests.has(name));
+                        for (const currentTestName of unprocessedTests) {
+                            const testcase = testcases[currentTestName];
+                            const testState = determineTestState(testcase);
+                            const test = this.testManager.findTestInSuite(currentSuite, currentTestName);
+                            if (test) {
+                                const dur = parseFloat(testcase.time || '0') * 1000;
+                                this.testManager.updateTestState(test, testState, new Date(), dur);
+                                this.#incrementCount(testState);
+                                const icon = this.#testIcon(testState);
+                                log.info(`  ${icon} ${currentTestName} (${(dur / 1000).toFixed(2)}s)`);
+                            }
+                            this.testManager.markTestAsProcessed(testFile, currentTestName);
+                        }
+                        if (processedTests.size === testcaseNames.length) {
+                            this.suiteManager.finalizeSuite(currentSuite);
+                            await new Promise((resolve) => setTimeout(resolve, TIMING.SUITE_COMPLETE_DELAY));
+                        }
+                    }
+                }
+                await this.sessionCapturer.captureTrace(browser);
+            }
+            catch (err) {
+                log.error(`Failed to capture trace: ${err.message}`);
+            }
+        }
+    }
+    async after(browser) {
+        try {
+            const currentTest = browser?.currentTest;
+            const testcases = currentTest?.results?.testcases || {};
+            for (const [, suite] of (this.suiteManager?.getAllSuites() ?? new Map()).entries()) {
+                this.testManager.finalizeSuiteTests(suite, testcases);
+                await new Promise((resolve) => setTimeout(resolve, TIMING.SUITE_COMPLETE_DELAY));
+                this.suiteManager.finalizeSuite(suite);
+            }
+            await new Promise((resolve) => setTimeout(resolve, TIMING.SUITE_COMPLETE_DELAY));
+            const summary = [
+                this.#passCount > 0 ? `${this.#passCount} passed` : null,
+                this.#failCount > 0 ? `${this.#failCount} failed` : null,
+                this.#skipCount > 0 ? `${this.#skipCount} skipped` : null
+            ]
+                .filter(Boolean)
+                .join('  ');
+            const totalFailed = this.#failCount;
+            log.info(`${totalFailed > 0 ? '❌' : '✅'} Tests complete!  ${summary}`);
+            log.info(`   DevTools UI: http://${this.options.hostname}:${this.options.port}`);
+            if (!this.#devtoolsBrowser) {
+                // Reuse mode: force one final suites broadcast so the UI reflects the
+                // actual outcome before the process exits.
+                this.testReporter?.updateSuites();
+                log.info('♻  Rerun complete — flushing WebSocket...');
+                await this.sessionCapturer?.closeWebSocket();
+                return;
+            }
+            log.info('💡 Please close the DevTools browser window to finish...');
+            if (this.#devtoolsBrowser) {
+                ;
+                logger.setLevel('devtools', 'warn');
+                let exitBySignal = false;
+                const signalHandler = () => {
+                    exitBySignal = true;
+                    log.info('\n✓ Exiting... Browser window will remain open');
+                    process.exit(0);
+                };
+                process.once('SIGINT', signalHandler);
+                process.once('SIGTERM', signalHandler);
+                while (true) {
+                    try {
+                        await this.#devtoolsBrowser.getTitle();
+                        await new Promise((res) => setTimeout(res, TIMING.BROWSER_POLL_INTERVAL));
+                    }
+                    catch {
+                        if (!exitBySignal) {
+                            log.info('Browser window closed, stopping DevTools app');
+                            break;
+                        }
+                    }
+                }
+                if (!exitBySignal) {
+                    process.removeListener('SIGINT', signalHandler);
+                    process.removeListener('SIGTERM', signalHandler);
+                    logger.setLevel('devtools', 'info');
+                    try {
+                        await this.#devtoolsBrowser.deleteSession();
+                    }
+                    catch {
+                        // session already closed
+                    }
+                    await stop();
+                    process.exit(0);
+                }
+            }
+        }
+        catch (err) {
+            log.error(`Failed to stop backend: ${err.message}`);
+        }
+    }
+    #buildMetadataOptions() {
+        return {
+            framework: this.#isCucumberRunner ? 'nightwatch-cucumber' : 'nightwatch',
+            configFile: this.#configPath,
+            baseDir: process.cwd(),
+            runCapabilities: {
+                canRunSuites: true,
+                canRunTests: !this.#isCucumberRunner,
+                canRunAll: false
+            }
+        };
+    }
+    #incrementCount(state) {
+        if (state === TEST_STATE.PASSED) {
+            this.#passCount++;
+        }
+        else if (state === TEST_STATE.SKIPPED) {
+            this.#skipCount++;
+        }
+        else {
+            this.#failCount++;
+        }
+    }
+    #testIcon(state) {
+        return state === TEST_STATE.PASSED
+            ? '✅'
+            : state === TEST_STATE.SKIPPED
+                ? '⏭'
+                : '❌';
+    }
+    registerEventHandlers(eventHub) {
+        this.#isCucumberRunner = eventHub.runner === 'cucumber';
+        if (this.#isCucumberRunner) {
+            log.info('✓ Cucumber runner detected via NightwatchEventHub');
+        }
+        log.info('✓ NightwatchEventHub registered — enriched metadata enabled');
+        const handleSessionMetadata = (data) => {
+            try {
+                const { sessionCapabilities, sessionId, testEnv, host, modulePath } = data?.metadata ?? {};
+                if (this.sessionCapturer && (sessionCapabilities || sessionId)) {
+                    this.sessionCapturer.sendUpstream('metadata', {
+                        type: TraceType.Testrunner,
+                        capabilities: sessionCapabilities ?? {},
+                        sessionId,
+                        testEnv,
+                        host,
+                        modulePath,
+                        options: this.#buildMetadataOptions()
+                    });
+                }
+            }
+            catch (err) {
+                log.error(`Error in event handler: ${err.message}`);
+            }
+        };
+        eventHub.on('TestSuiteStarted', handleSessionMetadata);
+        eventHub.on('TestRunStarted', handleSessionMetadata);
+    }
+}
+export const cucumberHooksPath = fileURLToPath(new URL('./helpers/cucumberHooks.cjs', import.meta.url));
+export default function createNightwatchDevTools(options) {
+    const plugin = new NightwatchDevToolsPlugin(options);
+    return {
+        // Set long timeout to allow user to review DevTools UI
+        // The after() hook waits for the browser window to be closed
+        asyncHookTimeout: 3600000,
+        before: async function () {
+            await plugin.before();
+        },
+        beforeEach: async function (browser) {
+            await plugin.beforeEach(browser);
+        },
+        afterEach: async function (browser) {
+            await plugin.afterEach(browser);
+        },
+        after: async function () {
+            await plugin.after();
+        },
+        registerEventHandlers: function (eventHub) {
+            plugin.registerEventHandlers(eventHub);
+        }
+    };
+}
+export { NightwatchDevToolsPlugin };
+//# sourceMappingURL=index.js.map