explorbot 0.1.16 → 0.1.18

package/dist/src/commands/explore-command.js

@@ -3,6 +3,7 @@ import { getStyles } from '../ai/planner/styles.js';
 import { outputPath } from '../config.js';
 import { normalizeUrl } from '../state-manager.js';
 import { Stats } from '../stats.js';
+import { TestResult } from '../test-plan.js';
 import { getCliName } from "../utils/cli-name.js";
 import { ErrorPageError } from "../utils/error-page.js";
 import { tag } from '../utils/logger.js';
@@ -11,12 +12,15 @@ import { printNextSteps, relativeToCwd } from "../utils/next-steps.js";
 import { safeFilename } from "../utils/strings.js";
 import { BaseCommand } from './base-command.js';
 const MAX_SUB_PAGE_ATTEMPTS = 30;
+const PRIORITY_ORDER = { critical: 0, important: 1, high: 2, normal: 3, low: 4 };
 export class ExploreCommand extends BaseCommand {
     name = 'explore';
     description = 'Start web exploration';
     options = [
         { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
         { flags: '--focus <feature>', description: 'Focus area for exploration' },
+        { flags: '--configure <spec>', description: 'Reuse spec: keys new|from|style|subpages|pick_by|priority, e.g. "new:25%;pick_by=random;priority=critical,high"' },
+        { flags: '--dry-run', description: 'Mark picked tests as skipped without executing or generating new ones' },
     ];
     suggestions = [
         { command: 'navigate <page>', hint: 'go to another page' },
@@ -24,93 +28,370 @@ export class ExploreCommand extends BaseCommand {
         { command: 'plan <feature>', hint: 'plan testing' },
     ];
     maxTests;
+    dryRun = false;
     testsRun = 0;
     completedPlans = [];
     failedSubPages = new Set();
+    oldTestRefs = new Set();
+    priorityFilter;
     async execute(args) {
         const { opts, args: remaining } = this.parseArgs(args);
         if (opts.maxTests) {
             this.maxTests = Number.parseInt(opts.maxTests, 10);
         }
         const feature = opts.focus || remaining.join(' ') || undefined;
+        const cfg = this.parseConfigure(opts.configure);
+        if (cfg.priorities)
+            this.priorityFilter = new Set(cfg.priorities);
+        if (opts.dryRun)
+            this.dryRun = true;
+        if (this.dryRun)
+            tag('info').log('Dry-run mode: planner runs to discover new tests; test execution is skipped');
         Stats.mode ??= 'explore';
         Stats.focus ??= feature;
         const mainUrl = this.explorBot.getExplorer().getStateManager().getCurrentState()?.url;
-        await this.runAllStyles(mainUrl, feature);
+        if (cfg.enabled) {
+            await this.runReuseMode(mainUrl, feature, cfg);
+        }
+        else {
+            await this.runFreshMode(mainUrl, feature, cfg.styles);
+        }
+        const mainPlan = this.completedPlans[0];
+        if (mainPlan)
+            this.explorBot.setCurrentPlan(mainPlan);
+        if (this.dryRun) {
+            this.printResults();
+            return;
+        }
+        if (mainUrl)
+            await this.explorBot.visit(mainUrl);
+        const savedPath = this.explorBot.savePlans(this.completedPlans);
+        this.printResults();
+        await this.explorBot.printSessionAnalysis();
+        this.printNextSteps(savedPath);
+    }
+    originLabel(test) {
+        return this.oldTestRefs.has(test) ? 'OLD' : 'NEW';
+    }
+    printPreview(label, tests) {
+        if (tests.length === 0)
+            return;
+        const lines = [label];
+        for (let i = 0; i < tests.length; i++) {
+            const t = tests[i];
+            lines.push(`  ${String(i + 1).padStart(2)}. [${this.originLabel(t)}] [${t.priority.padEnd(9)}] ${t.scenario}`);
+        }
+        tag('multiline').log(lines.join('\n'));
+    }
+    async runFreshMode(mainUrl, feature, styles) {
+        await this.runAllStyles(mainUrl, feature, undefined, undefined, styles);
         const mainPlan = this.explorBot.getCurrentPlan();
         if (!mainPlan)
             return;
         this.completedPlans.push(mainPlan);
-        if (!feature && !this.isLimitReached()) {
-            const planner = this.explorBot.agentPlanner();
-            let attempts = 0;
-            while (attempts < MAX_SUB_PAGE_ATTEMPTS) {
-                attempts++;
+        if (feature || this.isLimitReached())
+            return;
+        await this.discoverNewSubPages(mainPlan, mainUrl, styles, new Set());
+    }
+    async runReuseMode(mainUrl, feature, cfg) {
+        const filename = cfg.fromPath || this.explorBot.generatePlanFilename(feature);
+        let loadedPlans = [];
+        try {
+            loadedPlans = this.explorBot.loadPlans(filename);
+        }
+        catch (err) {
+            tag('warning').log(`Reuse plan not found (${err instanceof Error ? err.message : err}); falling back to fresh planning`);
+            await this.runFreshMode(mainUrl, feature, cfg.styles);
+            return;
+        }
+        if (loadedPlans.length === 0) {
+            tag('warning').log('Reuse plan empty; falling back to fresh planning');
+            await this.runFreshMode(mainUrl, feature, cfg.styles);
+            return;
+        }
+        const mainPlan = loadedPlans[0];
+        const subPlans = loadedPlans.slice(1);
+        const totalCap = this.maxTests ?? Number.POSITIVE_INFINITY;
+        let newQuota = Number.POSITIVE_INFINITY;
+        let oldQuota = Number.POSITIVE_INFINITY;
+        if (Number.isFinite(totalCap)) {
+            newQuota = Math.round(totalCap * cfg.newRatio);
+            oldQuota = Math.max(0, totalCap - newQuota);
+        }
+        for (const p of loadedPlans) {
+            for (const t of p.tests)
+                this.oldTestRefs.add(t);
+        }
+        const allOldTests = loadedPlans.flatMap((p) => p.tests.filter((t) => t.status === 'pending'));
+        let matchingOldTests = allOldTests;
+        if (cfg.styles) {
+            matchingOldTests = matchingOldTests.filter((t) => !t.style || cfg.styles.includes(t.style));
+        }
+        if (this.priorityFilter) {
+            matchingOldTests = matchingOldTests.filter((t) => this.priorityFilter.has(t.priority));
+        }
+        const pickBy = cfg.pickBy ?? 'priority';
+        const orderedOldTests = matchingOldTests.slice();
+        if (pickBy === 'priority') {
+            orderedOldTests.sort((a, b) => (PRIORITY_ORDER[a.priority] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99));
+        }
+        else if (pickBy === 'random') {
+            for (let i = orderedOldTests.length - 1; i > 0; i--) {
+                const j = Math.floor(Math.random() * (i + 1));
+                [orderedOldTests[i], orderedOldTests[j]] = [orderedOldTests[j], orderedOldTests[i]];
+            }
+        }
+        let pickCount = orderedOldTests.length;
+        if (Number.isFinite(oldQuota))
+            pickCount = Math.min(oldQuota, orderedOldTests.length);
+        const picked = orderedOldTests.slice(0, pickCount);
+        const pickedSet = new Set(picked);
+        for (const t of allOldTests) {
+            if (!pickedSet.has(t))
+                t.enabled = false;
+        }
+        let newQuotaLabel = 'unlimited';
+        if (Number.isFinite(newQuota))
+            newQuotaLabel = String(newQuota);
+        let priorityNote = '';
+        if (this.priorityFilter)
+            priorityNote = `, priority=[${[...this.priorityFilter].join(',')}]`;
+        tag('info').log(`Reuse: loaded ${allOldTests.length} old test(s), running ${picked.length} (pick_by=${pickBy}${priorityNote}), reserving ${newQuotaLabel} for new`);
+        const planner = this.explorBot.agentPlanner();
+        for (const p of loadedPlans)
+            planner.registerPlanInSession(p);
+        this.completedPlans.push(...loadedPlans);
+        this.printPreview(`Picked old tests (${picked.length}):`, picked);
+        let currentPlanRef;
+        for (const test of picked) {
+            if (this.isLimitReached())
+                break;
+            const owningPlan = test.plan;
+            if (owningPlan && owningPlan !== currentPlanRef) {
+                this.explorBot.setCurrentPlan(owningPlan);
+                if (owningPlan.url && !this.dryRun)
+                    await this.explorBot.visit(owningPlan.url);
+                currentPlanRef = owningPlan;
+            }
+            await this.runOneTest(test);
+        }
+        if (this.isLimitReached() || newQuota <= 0)
+            return;
+        const subpagesMode = cfg.subpages || 'both';
+        if (mainUrl && !this.dryRun)
+            await this.explorBot.visit(mainUrl);
+        await this.replanAndRun(mainUrl, feature, mainPlan, cfg.styles);
+        if (this.isLimitReached())
+            return;
+        if (subpagesMode === 'same' || subpagesMode === 'both') {
+            for (const subPlan of subPlans) {
                 if (this.isLimitReached())
                     break;
-                const candidates = planner.collectSubPageCandidates(mainPlan, mainUrl || '/').filter((c) => !this.failedSubPages.has(normalizeUrl(c.url)));
-                if (candidates.length === 0)
-                    break;
-                const pick = await planner.pickNextSubPage(candidates);
-                if (!pick)
-                    break;
-                tag('info').log(`Exploring sub-page: ${pick.url} (${pick.reason})`);
+                if (!subPlan.url)
+                    continue;
                 try {
-                    await this.explorBot.visit(pick.url);
-                    await this.runAllStyles(pick.url, undefined, mainPlan, this.completedPlans);
-                    const subPlan = this.explorBot.getCurrentPlan();
-                    if (subPlan) {
-                        this.completedPlans.push(subPlan);
-                    }
+                    if (!this.dryRun)
+                        await this.explorBot.visit(subPlan.url);
+                    await this.replanAndRun(subPlan.url, undefined, subPlan, cfg.styles);
                 }
                 catch (err) {
-                    this.failedSubPages.add(normalizeUrl(pick.url));
-                    tag('warning').log(`Sub-page exploration failed: ${err instanceof Error ? err.message : err}`);
+                    this.failedSubPages.add(normalizeUrl(subPlan.url));
+                    tag('warning').log(`Sub-page re-planning failed: ${err instanceof Error ? err.message : err}`);
                 }
             }
         }
-        this.explorBot.setCurrentPlan(mainPlan);
-        if (mainUrl)
-            await this.explorBot.visit(mainUrl);
-        const savedPath = this.explorBot.savePlans(this.completedPlans);
-        this.printResults();
-        await this.explorBot.printSessionAnalysis();
-        this.printNextSteps(savedPath);
+        if (this.isLimitReached())
+            return;
+        if (subpagesMode === 'new' || subpagesMode === 'both') {
+            const knownUrls = new Set();
+            for (const p of loadedPlans) {
+                if (p.url)
+                    knownUrls.add(normalizeUrl(p.url));
+            }
+            await this.discoverNewSubPages(mainPlan, mainUrl, cfg.styles, knownUrls);
+        }
     }
-    async runAllStyles(pageUrl, feature, parentPlan, completedPlans) {
+    async discoverNewSubPages(mainPlan, mainUrl, styles, knownUrls) {
+        const planner = this.explorBot.agentPlanner();
+        let attempts = 0;
+        while (attempts < MAX_SUB_PAGE_ATTEMPTS) {
+            attempts++;
+            if (this.isLimitReached())
+                break;
+            const candidates = planner.collectSubPageCandidates(mainPlan, mainUrl || '/').filter((c) => {
+                const norm = normalizeUrl(c.url);
+                return !this.failedSubPages.has(norm) && !knownUrls.has(norm);
+            });
+            if (candidates.length === 0)
+                break;
+            const pick = await planner.pickNextSubPage(candidates);
+            if (!pick)
+                break;
+            tag('info').log(`Exploring sub-page: ${pick.url} (${pick.reason})`);
+            try {
+                await this.explorBot.visit(pick.url);
+                await this.runAllStyles(pick.url, undefined, mainPlan, this.completedPlans, styles);
+                const subPlan = this.explorBot.getCurrentPlan();
+                if (subPlan && !this.completedPlans.includes(subPlan)) {
+                    this.completedPlans.push(subPlan);
+                }
+                knownUrls.add(normalizeUrl(pick.url));
+            }
+            catch (err) {
+                this.failedSubPages.add(normalizeUrl(pick.url));
+                tag('warning').log(`Sub-page exploration failed: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+    async replanAndRun(pageUrl, feature, existingPlan, styles) {
+        const styleList = styles ?? Object.keys(getStyles());
+        for (const style of styleList) {
+            if (this.isLimitReached())
+                break;
+            this.explorBot.setCurrentPlan(existingPlan);
+            const opts = { fresh: false, style, completedPlans: this.completedPlans };
+            if (this.dryRun)
+                opts.noSave = true;
+            await this.planWithRetry(feature, opts, pageUrl);
+            await this.runPendingTests();
+        }
+    }
+    async runAllStyles(pageUrl, feature, parentPlan, completedPlans, styles) {
+        const styleList = styles ?? Object.keys(getStyles());
         let fresh = true;
-        for (const style of Object.keys(getStyles())) {
-            if (!fresh && pageUrl) {
+        for (const style of styleList) {
+            if (!fresh && pageUrl && !this.dryRun) {
                 await this.explorBot.visit(pageUrl);
             }
             const opts = { fresh, style, completedPlans };
             if (fresh && parentPlan)
                 opts.extend = parentPlan;
+            if (this.dryRun)
+                opts.noSave = true;
             await this.planWithRetry(feature, opts, pageUrl);
             await this.runPendingTests();
             fresh = false;
         }
     }
     async planWithRetry(feature, opts, pageUrl) {
-        await this.explorBot.plan(feature, opts);
-        if (!this.explorBot.lastPlanError)
-            return;
-        if (this.explorBot.lastPlanError instanceof ErrorPageError) {
-            throw this.explorBot.lastPlanError;
-        }
-        tag('info').log(`Retrying planning style '${opts.style}'...`);
-        if (pageUrl)
-            await this.explorBot.visit(pageUrl);
+        const before = new Set(this.explorBot.getCurrentPlan()?.tests ?? []);
         await this.explorBot.plan(feature, opts);
         if (this.explorBot.lastPlanError) {
-            tag('warning').log(`Planning style '${opts.style}' failed after retry, skipping`);
+            if (this.explorBot.lastPlanError instanceof ErrorPageError) {
+                throw this.explorBot.lastPlanError;
+            }
+            tag('info').log(`Retrying planning style '${opts.style}'...`);
+            if (pageUrl && !this.dryRun)
+                await this.explorBot.visit(pageUrl);
+            await this.explorBot.plan(feature, opts);
+            if (this.explorBot.lastPlanError) {
+                tag('warning').log(`Planning style '${opts.style}' failed after retry, skipping`);
+                return;
+            }
+        }
+        const planAfter = this.explorBot.getCurrentPlan();
+        if (!planAfter)
+            return;
+        const added = planAfter.tests.filter((t) => !before.has(t));
+        if (added.length === 0)
+            return;
+        const urlNote = pageUrl ? ` for ${pageUrl}` : '';
+        this.printPreview(`Planner added ${added.length} new test(s) [style=${opts.style}]${urlNote}:`, added);
+    }
+    parseConfigure(raw) {
+        const cfg = { enabled: false, newRatio: 1.0 };
+        if (!raw)
+            return cfg;
+        const allStyles = Object.keys(getStyles());
+        const validSubpages = new Set(['none', 'same', 'new', 'both']);
+        let hasReuseSignal = false;
+        for (const pair of raw.split(';')) {
+            const trimmed = pair.trim();
+            if (!trimmed)
+                continue;
+            const sepMatch = trimmed.match(/^([^:=]+)\s*[:=]\s*(.*)$/);
+            if (!sepMatch) {
+                tag('warning').log(`Ignoring malformed configure pair: ${trimmed}`);
+                continue;
+            }
+            const key = sepMatch[1].trim().toLowerCase();
+            const value = sepMatch[2].trim();
+            if (key === 'new') {
+                const ratio = parseRatio(value);
+                if (ratio == null) {
+                    tag('warning').log(`Ignoring invalid 'new' value: ${value}`);
+                    continue;
+                }
+                cfg.newRatio = ratio;
+                hasReuseSignal = true;
+                continue;
+            }
+            if (key === 'from') {
+                cfg.fromPath = value;
+                hasReuseSignal = true;
+                continue;
+            }
+            if (key === 'style' || key === 'styles') {
+                const requested = value
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                const valid = [];
+                for (const s of requested) {
+                    if (allStyles.includes(s)) {
+                        valid.push(s);
+                        continue;
+                    }
+                    tag('warning').log(`Unknown planning style: ${s}`);
+                }
+                if (valid.length)
+                    cfg.styles = valid;
+                continue;
+            }
+            if (key === 'subpages') {
+                if (!validSubpages.has(value)) {
+                    tag('warning').log(`Ignoring invalid 'subpages' value: ${value}`);
+                    continue;
+                }
+                cfg.subpages = value;
+                continue;
+            }
+            if (key === 'pick_by' || key === 'pickby' || key === 'pick-by') {
+                if (value === 'priority' || value === 'random' || value === 'index') {
+                    cfg.pickBy = value;
+                    continue;
+                }
+                tag('warning').log(`Ignoring invalid 'pick_by' value: ${value} (use priority|random|index)`);
+                continue;
+            }
+            if (key === 'priority' || key === 'priorities') {
+                const requested = value
+                    .split(',')
+                    .map((s) => s.trim().toLowerCase())
+                    .filter(Boolean);
+                const valid = [];
+                for (const p of requested) {
+                    if (p in PRIORITY_ORDER) {
+                        valid.push(p);
+                        continue;
+                    }
+                    tag('warning').log(`Unknown priority: ${p} (use ${Object.keys(PRIORITY_ORDER).join('|')})`);
+                }
+                if (valid.length)
+                    cfg.priorities = valid;
+                continue;
+            }
+            tag('warning').log(`Unknown configure key: ${key}`);
         }
+        cfg.enabled = hasReuseSignal;
+        return cfg;
     }
     printResults() {
-        const allTests = this.completedPlans.flatMap((plan) => plan.tests.filter((t) => t.startTime != null).map((test) => ({ test, planTitle: plan.title })));
+        const allTests = this.completedPlans.flatMap((plan) => plan.tests.filter((t) => t.startTime != null).map((test) => ({ test, planTitle: plan.title }))).sort((a, b) => (a.test.startTime ?? 0) - (b.test.startTime ?? 0));
         if (allTests.length === 0)
             return;
         const hasSubPages = this.completedPlans.length > 1;
+        const hasOrigin = this.oldTestRefs.size > 0;
         const rows = allTests.map(({ test, planTitle }, index) => {
             const durationMs = test.getDurationMs();
             const duration = durationMs != null ? `${(durationMs / 1000).toFixed(1)}s` : '-';
@@ -127,12 +408,17 @@ export class ExploreCommand extends BaseCommand {
                 Time: duration,
                 Steps: String(Object.keys(test.notes).length),
             };
+            if (hasOrigin) {
+                row.Origin = this.originLabel(test);
+            }
             if (hasSubPages) {
                 row.Plan = planTitle;
             }
             return row;
         });
         const columns = ['#', 'Status', 'Title', 'Priority', 'Time', 'Steps'];
+        if (hasOrigin)
+            columns.push('Origin');
         if (hasSubPages)
             columns.push('Plan');
         tag('multiline').log(jsonToTable(rows, columns));
@@ -185,11 +471,41 @@ export class ExploreCommand extends BaseCommand {
         const plan = this.explorBot.getCurrentPlan();
         if (!plan)
             return;
+        if (this.priorityFilter) {
+            for (const t of plan.getPendingTests()) {
+                if (!this.priorityFilter.has(t.priority))
+                    t.enabled = false;
+            }
+        }
         for (const test of plan.getPendingTests()) {
             if (this.isLimitReached())
                 break;
+            await this.runOneTest(test);
+        }
+    }
+    async runOneTest(test) {
+        if (this.dryRun) {
+            test.start();
+            test.finish(TestResult.SKIPPED);
+        }
+        else {
             await this.explorBot.agentTester().test(test);
-            this.testsRun++;
         }
+        this.testsRun++;
+    }
+}
+function parseRatio(s) {
+    const trimmed = s.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.endsWith('%')) {
+        const n = Number.parseFloat(trimmed.slice(0, -1));
+        if (Number.isNaN(n) || n < 0 || n > 100)
+            return null;
+        return n / 100;
     }
+    const n = Number.parseFloat(trimmed);
+    if (Number.isNaN(n) || n < 0 || n > 1)
+        return null;
+    return n;
 }

package/dist/src/config.js

@@ -24,6 +24,7 @@ export class ConfigParser {
     static instance;
     config = null;
     configPath = null;
+    runtimeBaseUrlOverride = null;
     constructor() { }
     static loadEnv(filePath) {
         const resolved = resolve(filePath);
@@ -38,7 +39,7 @@ export class ConfigParser {
         return ConfigParser.instance;
     }
     async loadConfig(options) {
-        if (this.config && !options?.config && !options?.path) {
+        if (this.config && !options?.config && !options?.path && this.runtimeBaseUrlOverride === (options?.baseUrl || null)) {
             return this.config;
         }
         // Store the initial working directory for reference
@@ -61,7 +62,8 @@ export class ConfigParser {
             if (!loadedConfig) {
                 throw new Error('Configuration file is empty or invalid');
             }
-            this.config = this.resolveConfig(loadedConfig);
+            this.config = this.resolveConfig(loadedConfig, options);
+            this.runtimeBaseUrlOverride = options?.baseUrl || null;
             this.configPath = resolvedPath;
             log(`Configuration loaded from: ${resolvedPath}`);
             // Restore original directory after successful config load
@@ -108,6 +110,7 @@ export class ConfigParser {
         if (ConfigParser.instance) {
             ConfigParser.instance.config = null;
             ConfigParser.instance.configPath = null;
+            ConfigParser.instance.runtimeBaseUrlOverride = null;
         }
     }
     // For testing purposes only - sets up minimal default config
@@ -185,11 +188,15 @@ export class ConfigParser {
             return JSON.parse(content);
         }
     }
-    resolveConfig(config) {
+    resolveConfig(config, options) {
         if (config.web?.url && !config.playwright?.url) {
             config.playwright = config.playwright || { browser: 'chromium', url: '' };
             config.playwright.url = config.web.url;
         }
+        if (options?.baseUrl) {
+            config.playwright = config.playwright || { browser: 'chromium', url: '' };
+            config.playwright.url = options.baseUrl;
+        }
         return config;
     }
     validateConfig(config) {

package/dist/src/explorbot.js

@@ -24,6 +24,7 @@ import { ExperienceTracker } from "./experience-tracker.js";
 import Explorer from "./explorer.js";
 import { KnowledgeTracker } from "./knowledge-tracker.js";
 import { Plan } from "./test-plan.js";
+import { parsePlansFromMarkdown } from "./utils/test-plan-markdown.js";
 import { setVerboseMode, tag } from "./utils/logger.js";
 import { relativeToCwd } from "./utils/next-steps.js";
 import { sanitizeFilename } from "./utils/strings.js";
@@ -323,7 +324,8 @@ export class ExplorBot {
                 return undefined;
             return this.currentPlan;
         }
-        this.savePlan();
+        if (!opts.noSave)
+            this.savePlan();
         return this.currentPlan;
     }
     getPlansDir() {
@@ -348,20 +350,21 @@ export class ExplorBot {
         this.lastSavedPlanPath = planPath;
         return planPath;
     }
-    generatePlanFilename() {
+    generatePlanFilename(feature) {
         const state = this.explorer?.getStateManager().getCurrentState();
         const urlPath = state?.url || '/';
         const urlPart = sanitizeFilename(urlPath) || 'root';
         const suffix = '.md';
-        if (!this.planFeature)
+        const f = feature ?? this.planFeature;
+        if (!f)
             return urlPart.slice(0, 256 - suffix.length) + suffix;
-        const featurePart = `_${sanitizeFilename(this.planFeature)}`;
+        const featurePart = `_${sanitizeFilename(f)}`;
         const maxFeatureLen = 256 - suffix.length - urlPart.length;
         if (maxFeatureLen <= 1)
             return urlPart.slice(0, 256 - suffix.length) + suffix;
         return urlPart + featurePart.slice(0, maxFeatureLen) + suffix;
     }
-    loadPlan(filename) {
+    resolvePlanPath(filename) {
         let planPath = filename;
         if (path.isAbsolute(filename)) {
             if (!existsSync(planPath) && !filename.endsWith('.md')) {
@@ -378,12 +381,23 @@ export class ExplorBot {
                 planPath = path.join(plansDir, `${filename}.md`);
             }
         }
+        return planPath;
+    }
+    loadPlan(filename) {
+        const planPath = this.resolvePlanPath(filename);
         if (!existsSync(planPath)) {
             throw new Error(`Plan file not found: ${planPath}`);
         }
         this.setCurrentPlan(Plan.fromMarkdown(planPath));
         return this.currentPlan;
     }
+    loadPlans(filename) {
+        const planPath = this.resolvePlanPath(filename);
+        if (!existsSync(planPath)) {
+            throw new Error(`Plan file not found: ${planPath}`);
+        }
+        return parsePlansFromMarkdown(planPath);
+    }
     setCurrentPlan(plan) {
         this.currentPlan = plan;
         if (plan && !this.sessionPlans.includes(plan)) {

package/dist/src/explorer.js

@@ -189,7 +189,20 @@ class Explorer {
         }
         await this.connectOrLaunchBrowser();
         const hasSession = this.options?.session && existsSync(this.options.session);
-        const contextOptions = hasSession ? { storageState: this.options.session } : undefined;
+        const helperOptions = this.playwrightHelper.options || {};
+        // CodeceptJS skips _createContextPage when sessions/storageState are involved, so we
+        // build contextOptions ourselves. Most keys share a name with Playwright's
+        // BrowserContextOptions and are copied as-is; `emulate` must be flattened, `basicAuth`
+        // renamed to `httpCredentials`, and `storageState` comes from the --session flag.
+        const contextOptions = {
+            ...helperOptions,
+        };
+        if (helperOptions.emulate)
+            Object.assign(contextOptions, helperOptions.emulate);
+        if (helperOptions.basicAuth)
+            contextOptions.httpCredentials = helperOptions.basicAuth;
+        if (hasSession)
+            contextOptions.storageState = this.options.session;
         await this.playwrightHelper._createContextPage(contextOptions);
         await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
         this.setupXhrCapture();

package/dist/src/state-manager.js

@@ -416,6 +416,9 @@ export class StateManager {
     }
 }
 export function normalizeUrl(url) {
+    if (url.startsWith('/')) {
+        return url.replace(/^\/+/, '').replace(/\/+$/g, '');
+    }
     try {
         const parsed = new URL(url, 'http://localhost');
         const path = parsed.pathname.replace(/^\/+|\/+$/g, '');

package/dist/src/utils/test-plan-markdown.js

@@ -145,8 +145,15 @@ export function parsePlansFromMarkdown(filePath) {
             continue;
         if (line.startsWith('<!-- test')) {
             currentTest = null;
-            const priorityMatch = line.match(/priority:\s*(\w+)/);
+            let block = line;
+            let j = i;
+            while (!block.includes('-->') && j + 1 < lines.length) {
+                j++;
+                block += `\n${lines[j].trim()}`;
+            }
+            const priorityMatch = block.match(/priority:\s*(\w+)/);
             priority = priorityMatch?.[1] || 'normal';
+            i = j;
             continue;
         }
         if (line.startsWith('# ') && currentTest === null) {