@portel/photon 1.10.0 → 1.12.0

package/dist/test-runner.js

@@ -1,7 +1,10 @@
 /**
  * Photon Test Runner
  *
- * Discovers and runs test* methods in photons
+ * Discovers and runs tests from:
+ * - External .test.ts files (preferred — companion to .photon.ts)
+ * - Inline test* methods in .photon.ts (legacy, backward compatible)
+ *
  * Supports multiple test modes:
  * - direct: Call methods directly on instance (unit tests)
  * - cli: Call methods via CLI subprocess (integration tests)
@@ -10,19 +13,347 @@
  * Usage: photon test [photon] [testName] [--mode direct|cli|all]
  */
 import * as path from 'path';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync, readdirSync } from 'fs';
 import { spawn } from 'child_process';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { PhotonLoader } from './loader.js';
 import { listPhotonMCPs, resolvePhotonPath } from './path-resolver.js';
 import { logger } from './shared/logger.js';
-import { SchemaExtractor } from '@portel/photon-core';
+import { SchemaExtractor, compilePhotonTS } from '@portel/photon-core';
 import chalk from 'chalk';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Get the path to the CLI binary (either local dev or installed)
 const CLI_PATH = path.resolve(__dirname, 'cli.js');
 // ══════════════════════════════════════════════════════════════════════════════
+// EXTERNAL TEST FILE DISCOVERY & EXECUTION
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Resolve the companion .test.ts path for a photon file.
+ * e.g. /path/to/todo.photon.ts → /path/to/todo.test.ts
+ */
+function resolveTestFilePath(photonPath) {
+    const testPath = photonPath.replace(/\.photon\.ts$/, '.test.ts');
+    return existsSync(testPath) ? testPath : null;
+}
+/**
+ * Parse JSDoc tags (@skip, @only) from a .test.ts source file.
+ * Returns a map of export name → { skip?, only? }.
+ */
+function parseTestTags(source) {
+    const tags = new Map();
+    // Match JSDoc comment followed by export
+    const pattern = /\/\*\*([\s\S]*?)\*\/\s*export\s+(?:async\s+)?(?:function\s+|const\s+)(\w+)/g;
+    let match;
+    while ((match = pattern.exec(source)) !== null) {
+        const comment = match[1];
+        const name = match[2];
+        const entry = {};
+        const skipMatch = comment.match(/@skip(?:\s+(.+?))?(?:\n|\*)/);
+        if (skipMatch) {
+            entry.skip = skipMatch[1]?.trim() || 'skipped';
+        }
+        if (/@only\b/.test(comment)) {
+            entry.only = true;
+        }
+        tags.set(name, entry);
+    }
+    return tags;
+}
+/**
+ * Discover and compile a .test.ts file, returning test descriptors and hooks.
+ */
+async function discoverExternalTests(testFilePath) {
+    try {
+        const source = readFileSync(testFilePath, 'utf-8');
+        const tags = parseTestTags(source);
+        // Compile the test file
+        const cacheDir = path.join(path.dirname(testFilePath), '.photon-cache', 'tests');
+        const jsPath = await compilePhotonTS(testFilePath, { cacheDir });
+        // Import the compiled module
+        const moduleUrl = pathToFileURL(jsPath).href;
+        const mod = await import(moduleUrl);
+        const tests = [];
+        const hooks = {};
+        for (const [key, value] of Object.entries(mod)) {
+            // Lifecycle hooks
+            if (key === 'beforeAll' && typeof value === 'function') {
+                hooks.beforeAll = value;
+                continue;
+            }
+            if (key === 'afterAll' && typeof value === 'function') {
+                hooks.afterAll = value;
+                continue;
+            }
+            if (key === 'beforeEach' && typeof value === 'function') {
+                hooks.beforeEach = value;
+                continue;
+            }
+            if (key === 'afterEach' && typeof value === 'function') {
+                hooks.afterEach = value;
+                continue;
+            }
+            // Test functions
+            if (key.startsWith('test') && typeof value === 'function') {
+                const tagInfo = tags.get(key);
+                tests.push({
+                    name: key,
+                    fn: value,
+                    skip: tagInfo?.skip,
+                    only: tagInfo?.only,
+                });
+            }
+            // Sequence tests (exported arrays of functions)
+            if (key.startsWith('test') && Array.isArray(value)) {
+                const tagInfo = tags.get(key);
+                const steps = value
+                    .filter((fn) => typeof fn === 'function')
+                    .map((fn) => ({ name: fn.name || 'anonymous', fn }));
+                if (steps.length > 0) {
+                    tests.push({
+                        name: key,
+                        steps,
+                        skip: tagInfo?.skip,
+                        only: tagInfo?.only,
+                    });
+                }
+            }
+        }
+        return { tests, hooks };
+    }
+    catch (error) {
+        logger.error(`Failed to discover external tests from ${testFilePath}: ${error.message}`);
+        return null;
+    }
+}
+/**
+ * Run a single external test function with a fresh photon instance.
+ */
+async function runExternalTest(testFn, photonPath, photonName, testName, workingDir, hooks) {
+    const start = Date.now();
+    let loadError = null;
+    try {
+        // Create a fresh instance for isolation
+        let instance = null;
+        try {
+            const loader = new PhotonLoader(false);
+            const loaded = await loader.loadFile(photonPath);
+            instance = loaded.instance;
+        }
+        catch (err) {
+            loadError = err.message;
+            // Create a minimal stub so test functions can check isConnected() etc.
+            instance = {};
+        }
+        // Run beforeEach hook
+        if (hooks?.beforeEach) {
+            try {
+                await hooks.beforeEach(instance);
+            }
+            catch {
+                // beforeEach may fail on stub instance — ignore
+            }
+        }
+        try {
+            const result = await testFn(instance);
+            const duration = Date.now() - start;
+            // Same contract as inline tests: explicit { passed: false } or throw
+            if (result && typeof result === 'object') {
+                if (result.skipped === true) {
+                    return {
+                        photon: photonName,
+                        test: testName,
+                        passed: true,
+                        skipped: true,
+                        duration,
+                        message: result.reason || 'Skipped',
+                        mode: 'direct',
+                    };
+                }
+                if (result.passed === false) {
+                    const failResult = {
+                        photon: photonName,
+                        test: testName,
+                        passed: false,
+                        duration,
+                        error: result.error || result.message || 'Test returned passed: false',
+                        mode: 'direct',
+                    };
+                    failResult.issueUrl = generateIssueUrl(failResult, workingDir);
+                    return failResult;
+                }
+            }
+            return { photon: photonName, test: testName, passed: true, duration, mode: 'direct' };
+        }
+        finally {
+            // Run afterEach hook (always, even on failure)
+            if (hooks?.afterEach) {
+                try {
+                    await hooks.afterEach(instance);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+        }
+    }
+    catch (error) {
+        const duration = Date.now() - start;
+        // If the photon failed to load and the test also failed,
+        // report as skipped (the test couldn't run due to missing config)
+        if (loadError) {
+            return {
+                photon: photonName,
+                test: testName,
+                passed: true,
+                skipped: true,
+                duration,
+                message: `Photon not configured: ${loadError.split('\n')[0]}`,
+                mode: 'direct',
+            };
+        }
+        const failResult = {
+            photon: photonName,
+            test: testName,
+            passed: false,
+            duration,
+            error: error.message || String(error),
+            mode: 'direct',
+        };
+        failResult.issueUrl = generateIssueUrl(failResult, workingDir);
+        return failResult;
+    }
+}
+/**
+ * Run a sequence test: all steps share one photon instance.
+ */
+async function runExternalSequence(steps, photonPath, photonName, sequenceName, workingDir) {
+    const results = [];
+    try {
+        const loader = new PhotonLoader(false);
+        const loaded = await loader.loadFile(photonPath);
+        const instance = loaded.instance;
+        for (const step of steps) {
+            const stepTestName = `${sequenceName}/${step.name}`;
+            const start = Date.now();
+            try {
+                await step.fn(instance);
+                results.push({
+                    photon: photonName,
+                    test: stepTestName,
+                    passed: true,
+                    duration: Date.now() - start,
+                    mode: 'direct',
+                });
+            }
+            catch (error) {
+                const failResult = {
+                    photon: photonName,
+                    test: stepTestName,
+                    passed: false,
+                    duration: Date.now() - start,
+                    error: error.message || String(error),
+                    mode: 'direct',
+                };
+                failResult.issueUrl = generateIssueUrl(failResult, workingDir);
+                results.push(failResult);
+                // Abort remaining steps on failure
+                for (const remaining of steps.slice(steps.indexOf(step) + 1)) {
+                    results.push({
+                        photon: photonName,
+                        test: `${sequenceName}/${remaining.name}`,
+                        passed: false,
+                        skipped: true,
+                        duration: 0,
+                        message: 'Skipped (previous step failed)',
+                        mode: 'direct',
+                    });
+                }
+                break;
+            }
+        }
+    }
+    catch (error) {
+        results.push({
+            photon: photonName,
+            test: `${sequenceName}/*`,
+            passed: false,
+            duration: 0,
+            error: `Failed to load photon: ${error.message}`,
+            mode: 'direct',
+        });
+    }
+    return results;
+}
+/**
+ * Run all external tests from a .test.ts file.
+ */
+async function runExternalTests(testFilePath, photonPath, photonName, workingDir, specificTest) {
+    const discovered = await discoverExternalTests(testFilePath);
+    if (!discovered || discovered.tests.length === 0)
+        return [];
+    const { tests, hooks } = discovered;
+    const results = [];
+    // Filter by specific test name if provided
+    let testsToRun = specificTest
+        ? tests.filter((t) => t.name === specificTest || t.name === `test${specificTest}`)
+        : tests;
+    // Handle @only: if any test has @only, run only those
+    const onlyTests = testsToRun.filter((t) => t.only);
+    if (onlyTests.length > 0) {
+        testsToRun = onlyTests;
+    }
+    // Run beforeAll hook (with a temporary instance)
+    if (hooks.beforeAll) {
+        try {
+            const loader = new PhotonLoader(false);
+            const loaded = await loader.loadFile(photonPath);
+            await hooks.beforeAll(loaded.instance);
+        }
+        catch {
+            // beforeAll may fail if photon can't load (missing config) —
+            // individual tests will handle this gracefully via stub instance
+        }
+    }
+    for (const test of testsToRun) {
+        // Handle @skip
+        if (test.skip) {
+            results.push({
+                photon: photonName,
+                test: test.name,
+                passed: true,
+                skipped: true,
+                duration: 0,
+                message: typeof test.skip === 'string' ? test.skip : 'Skipped',
+                mode: 'direct',
+            });
+            continue;
+        }
+        if (test.steps) {
+            // Sequence test
+            const seqResults = await runExternalSequence(test.steps, photonPath, photonName, test.name, workingDir);
+            results.push(...seqResults);
+        }
+        else if (test.fn) {
+            // Regular test
+            const result = await runExternalTest(test.fn, photonPath, photonName, test.name, workingDir, hooks);
+            results.push(result);
+        }
+    }
+    // Run afterAll hook
+    if (hooks.afterAll) {
+        try {
+            const loader = new PhotonLoader(false);
+            const loaded = await loader.loadFile(photonPath);
+            await hooks.afterAll(loaded.instance);
+        }
+        catch {
+            // afterAll may fail if photon can't load — ignore gracefully
+        }
+    }
+    return results;
+}
+// ══════════════════════════════════════════════════════════════════════════════
 // ISSUE URL GENERATOR
 // ══════════════════════════════════════════════════════════════════════════════
 const ISSUE_REPO = 'https://github.com/anthropics/photon';
@@ -421,137 +752,142 @@ async function runMcpTest(photonPath, photonName, methodName, params, workingDir
  */
 async function runPhotonTests(photonPath, photonName, workingDir, mode, specificTest) {
     const results = [];
+    // ─────────────────────────────────────────────────────────────────────────
+    // EXTERNAL .test.ts FILE (preferred — runs first, creates own instances)
+    // ─────────────────────────────────────────────────────────────────────────
+    let hasExternalTests = false;
+    if (mode === 'direct' || mode === 'all') {
+        const testFilePath = resolveTestFilePath(photonPath);
+        if (testFilePath) {
+            hasExternalTests = true;
+            const externalResults = await runExternalTests(testFilePath, photonPath, photonName, workingDir, specificTest);
+            results.push(...externalResults);
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // INLINE test* METHODS (legacy — skipped when external tests exist)
+    // ─────────────────────────────────────────────────────────────────────────
+    // Load the photon instance (needed for inline tests and CLI/MCP tests)
     const loader = new PhotonLoader(false);
+    let instance = null;
     try {
         const photon = await loader.loadFile(photonPath);
-        const instance = photon.instance;
-        if (!instance) {
+        instance = photon.instance;
+    }
+    catch (error) {
+        // If external tests already ran, load failure is fine (they create own instances)
+        if (!hasExternalTests && (mode === 'direct' || mode === 'all')) {
             return [
                 {
                     photon: photonName,
                     test: '*',
                     passed: false,
                     duration: 0,
-                    error: 'Failed to load photon instance',
+                    error: `Failed to load photon: ${error.message}`,
                     mode: 'direct',
                 },
             ];
         }
-        // ─────────────────────────────────────────────────────────────────────────
-        // DIRECT TESTS (test* methods)
-        // ─────────────────────────────────────────────────────────────────────────
-        if (mode === 'direct' || mode === 'all') {
-            const testMethods = getTestMethods(instance);
-            if (testMethods.length > 0) {
-                // Filter to specific test if requested
-                const testsToRun = specificTest
-                    ? testMethods.filter((t) => t === specificTest || t === `test${specificTest}`)
-                    : testMethods;
-                if (specificTest && testsToRun.length === 0 && mode === 'direct') {
+    }
+    if (!hasExternalTests && (mode === 'direct' || mode === 'all') && instance) {
+        const testMethods = getTestMethods(instance);
+        if (testMethods.length > 0) {
+            // Filter to specific test if requested
+            const testsToRun = specificTest
+                ? testMethods.filter((t) => t === specificTest || t === `test${specificTest}`)
+                : testMethods;
+            if (specificTest && testsToRun.length === 0 && mode === 'direct') {
+                return [
+                    {
+                        photon: photonName,
+                        test: specificTest,
+                        passed: false,
+                        duration: 0,
+                        error: `Test not found: ${specificTest}`,
+                        mode: 'direct',
+                    },
+                ];
+            }
+            // Run testBeforeAll if it exists
+            if (hasLifecycleHook(instance, 'testBeforeAll')) {
+                try {
+                    await instance.testBeforeAll();
+                }
+                catch (error) {
                     return [
                         {
                             photon: photonName,
-                            test: specificTest,
+                            test: 'beforeAll',
                             passed: false,
                             duration: 0,
-                            error: `Test not found: ${specificTest}`,
+                            error: `Setup failed: ${error.message}`,
                             mode: 'direct',
                         },
                     ];
                 }
-                // Run testBeforeAll if it exists
-                if (hasLifecycleHook(instance, 'testBeforeAll')) {
-                    try {
-                        await instance.testBeforeAll();
-                    }
-                    catch (error) {
-                        return [
-                            {
-                                photon: photonName,
-                                test: 'beforeAll',
-                                passed: false,
-                                duration: 0,
-                                error: `Setup failed: ${error.message}`,
-                                mode: 'direct',
-                            },
-                        ];
-                    }
-                }
-                // Run direct tests
-                for (const testName of testsToRun) {
-                    const result = await runDirectTest(instance, photonName, testName, workingDir);
-                    results.push(result);
-                }
-                // Run testAfterAll if it exists
-                if (hasLifecycleHook(instance, 'testAfterAll')) {
-                    try {
-                        await instance.testAfterAll();
-                    }
-                    catch (error) {
-                        results.push({
-                            photon: photonName,
-                            test: 'afterAll',
-                            passed: false,
-                            duration: 0,
-                            error: `Teardown failed: ${error.message}`,
-                            mode: 'direct',
-                        });
-                    }
-                }
             }
-        }
-        // ─────────────────────────────────────────────────────────────────────────
-        // CLI INTERFACE TESTS
-        // ─────────────────────────────────────────────────────────────────────────
-        if (mode === 'cli' || mode === 'all') {
-            const methods = await getPublicMethods(photonPath);
-            for (const method of methods) {
-                // Skip test methods and lifecycle hooks in interface tests
-                if (method.name.startsWith('test') || method.name.startsWith('on')) {
-                    continue;
-                }
-                // Skip if specific test requested and doesn't match
-                if (specificTest && !`cli:${method.name}`.includes(specificTest)) {
-                    continue;
-                }
-                const params = buildExampleParams(method);
-                const result = await runCliTest(photonName, method.name, params, workingDir);
+            // Run direct tests
+            for (const testName of testsToRun) {
+                const result = await runDirectTest(instance, photonName, testName, workingDir);
                 results.push(result);
             }
-        }
-        // ─────────────────────────────────────────────────────────────────────────
-        // MCP INTERFACE TESTS
-        // ─────────────────────────────────────────────────────────────────────────
-        if (mode === 'mcp' || mode === 'all') {
-            const methods = await getPublicMethods(photonPath);
-            for (const method of methods) {
-                // Skip test methods and lifecycle hooks in interface tests
-                if (method.name.startsWith('test') || method.name.startsWith('on')) {
-                    continue;
+            // Run testAfterAll if it exists
+            if (hasLifecycleHook(instance, 'testAfterAll')) {
+                try {
+                    await instance.testAfterAll();
                 }
-                // Skip if specific test requested and doesn't match
-                if (specificTest && !`mcp:${method.name}`.includes(specificTest)) {
-                    continue;
+                catch (error) {
+                    results.push({
+                        photon: photonName,
+                        test: 'afterAll',
+                        passed: false,
+                        duration: 0,
+                        error: `Teardown failed: ${error.message}`,
+                        mode: 'direct',
+                    });
                 }
-                const params = buildExampleParams(method);
-                const result = await runMcpTest(photonPath, photonName, method.name, params, workingDir);
-                results.push(result);
             }
         }
-        return results;
     }
-    catch (error) {
-        return [
-            {
-                photon: photonName,
-                test: '*',
-                passed: false,
-                duration: 0,
-                error: `Failed to load photon: ${error.message}`,
-                mode: 'direct',
-            },
-        ];
+    // ─────────────────────────────────────────────────────────────────────────
+    // CLI INTERFACE TESTS
+    // ─────────────────────────────────────────────────────────────────────────
+    if (mode === 'cli' || mode === 'all') {
+        const methods = await getPublicMethods(photonPath);
+        for (const method of methods) {
+            // Skip test methods and lifecycle hooks in interface tests
+            if (method.name.startsWith('test') || method.name.startsWith('on')) {
+                continue;
+            }
+            // Skip if specific test requested and doesn't match
+            if (specificTest && !`cli:${method.name}`.includes(specificTest)) {
+                continue;
+            }
+            const params = buildExampleParams(method);
+            const result = await runCliTest(photonName, method.name, params, workingDir);
+            results.push(result);
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // MCP INTERFACE TESTS
+    // ─────────────────────────────────────────────────────────────────────────
+    if (mode === 'mcp' || mode === 'all') {
+        const methods = await getPublicMethods(photonPath);
+        for (const method of methods) {
+            // Skip test methods and lifecycle hooks in interface tests
+            if (method.name.startsWith('test') || method.name.startsWith('on')) {
+                continue;
+            }
+            // Skip if specific test requested and doesn't match
+            if (specificTest && !`mcp:${method.name}`.includes(specificTest)) {
+                continue;
+            }
+            const params = buildExampleParams(method);
+            const result = await runMcpTest(photonPath, photonName, method.name, params, workingDir);
+            results.push(result);
+        }
     }
+    return results;
 }
 // ══════════════════════════════════════════════════════════════════════════════
 // OUTPUT FORMATTING
@@ -641,6 +977,39 @@ function printSummary(summary) {
 // ══════════════════════════════════════════════════════════════════════════════
 // PUBLIC API
 // ══════════════════════════════════════════════════════════════════════════════
+/**
+ * List all tests for a photon (external + inline).
+ * Used by Beam UI to discover available tests.
+ */
+export async function listTests(photonPath, instance) {
+    const tests = [];
+    // External .test.ts tests
+    const testFilePath = resolveTestFilePath(photonPath);
+    if (testFilePath) {
+        const discovered = await discoverExternalTests(testFilePath);
+        if (discovered) {
+            for (const t of discovered.tests) {
+                if (t.steps) {
+                    // Sequence: list each step
+                    for (const step of t.steps) {
+                        tests.push({ name: `${t.name}/${step.name}`, source: 'external', skip: t.skip });
+                    }
+                }
+                else {
+                    tests.push({ name: t.name, source: 'external', skip: t.skip });
+                }
+            }
+        }
+    }
+    // Inline test* methods
+    if (instance) {
+        const inlineMethods = getTestMethods(instance);
+        for (const name of inlineMethods) {
+            tests.push({ name, source: 'inline' });
+        }
+    }
+    return tests;
+}
 /**
  * Main test runner
  */
@@ -648,16 +1017,31 @@ export async function runTests(workingDir, photonName, testName, options = {}) {
     const startTime = Date.now();
     const results = [];
     const mode = options.mode || 'direct';
+    // Also scan CWD for photon files (development repos)
+    const cwd = process.cwd();
+    const cwdIsDifferent = path.resolve(cwd) !== path.resolve(workingDir);
     if (!options.json) {
         console.log('');
         console.log(chalk.bold('⚡ Photon Test Runner'));
         console.log(chalk.gray(`   ${workingDir}`));
+        if (cwdIsDifferent) {
+            console.log(chalk.gray(`   ${cwd} ${chalk.cyan('(dev)')}`));
+        }
         console.log(chalk.gray(`   Mode: ${mode}`));
         console.log('');
     }
     if (photonName) {
-        // Run tests for specific photon
-        const photonPath = await resolvePhotonPath(photonName, workingDir);
+        // Run tests for specific photon — check CWD first, then installed dir
+        let photonPath = null;
+        if (cwdIsDifferent) {
+            const cwdCandidate = path.join(cwd, `${photonName}.photon.ts`);
+            if (existsSync(cwdCandidate)) {
+                photonPath = cwdCandidate;
+            }
+        }
+        if (!photonPath) {
+            photonPath = await resolvePhotonPath(photonName, workingDir);
+        }
         if (!photonPath) {
             logger.error(`Photon not found: ${photonName}`);
             process.exit(1);
@@ -675,11 +1059,32 @@ export async function runTests(workingDir, photonName, testName, options = {}) {
         }
     }
     else {
-        // Run tests for all photons
-        const photons = await listPhotonMCPs(workingDir);
-        if (photons.length === 0) {
+        // Run tests for all photons — merge installed + CWD photons
+        const installedPhotons = await listPhotonMCPs(workingDir);
+        // Build a map of photon name → path, CWD photons take priority
+        const photonMap = new Map();
+        for (const name of installedPhotons) {
+            const p = path.join(workingDir, `${name}.photon.ts`);
+            if (existsSync(p)) {
+                photonMap.set(name, p);
+            }
+        }
+        // Discover photons in CWD (development repos)
+        if (cwdIsDifferent && existsSync(cwd)) {
+            try {
+                const cwdFiles = readdirSync(cwd).filter((f) => f.endsWith('.photon.ts'));
+                for (const file of cwdFiles) {
+                    const name = file.replace(/\.photon\.ts$/, '');
+                    photonMap.set(name, path.join(cwd, file)); // CWD overrides installed
+                }
+            }
+            catch {
+                // Ignore CWD read errors
+            }
+        }
+        if (photonMap.size === 0) {
             if (!options.json) {
-                console.log(chalk.yellow('No photons found in working directory'));
+                console.log(chalk.yellow('No photons found'));
             }
             return {
                 total: 0,
@@ -691,23 +1096,25 @@ export async function runTests(workingDir, photonName, testName, options = {}) {
                 mode,
             };
         }
-        for (const photon of photons) {
-            const photonPath = path.join(workingDir, `${photon}.photon.ts`);
+        for (const [photon, photonPath] of photonMap) {
             if (!existsSync(photonPath)) {
                 continue;
             }
-            // Check if photon has any test methods before printing header (for direct mode)
+            // Check if photon has any tests (external .test.ts or inline test* methods)
             if (mode === 'direct') {
-                const loader = new PhotonLoader(false);
-                try {
-                    const loaded = await loader.loadFile(photonPath);
-                    const testMethods = getTestMethods(loaded.instance);
-                    if (testMethods.length === 0) {
-                        continue; // Skip photons with no tests in direct mode
+                const hasExternalTests = resolveTestFilePath(photonPath) !== null;
+                if (!hasExternalTests) {
+                    const loader = new PhotonLoader(false);
+                    try {
+                        const loaded = await loader.loadFile(photonPath);
+                        const testMethods = getTestMethods(loaded.instance);
+                        if (testMethods.length === 0) {
+                            continue; // Skip photons with no tests in direct mode
+                        }
+                    }
+                    catch {
+                        continue;
                     }
-                }
-                catch {
-                    continue;
                 }
             }
             if (!options.json) {