detox.session.start
Start a Detox testing session to enable UI automation for React Native/Expo iOS applications. Required before executing UI actions in automated tests.
Instructions
Start a Detox testing session. Required before running UI actions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| configuration | No | Detox configuration name. Defaults to config value. | |
| reuse | No | Reuse existing session if available. |
Implementation Reference
- src/detox/runner.ts:188-273 (handler)The main handler function that starts the Detox session by generating and running a warmup test using the detox CLI, updating the state manager, and handling errors.export async function startDetoxSession(configuration?: string): Promise<{ sessionId: string; configuration: string; }> { logger.info("detox", "Starting Detox session"); if (!hasConfig()) { throw createError("CONFIG_NOT_FOUND", "Configuration required for Detox session"); } const config = getConfig(); const detoxConfig = configuration ?? config.detox.configuration; const sessionId = uuidv4(); stateManager.updateDetox({ state: "starting", configuration: detoxConfig, }); // Run a warmup/healthcheck action try { // Generate a simple noop test to warm up Detox const template = await loadTemplate(); const warmupCode = ejs.render(template, { timestamp: new Date().toISOString(), actionName: "warmup", actionSnippet: "// Warmup - no action", launchApp: true, captureData: false, }); const testDir = join(config.projectPath, ".mcp-detox-tmp"); const testFile = join(testDir, "mcp-warmup.test.js"); if (!existsSync(testDir)) { await mkdir(testDir, { recursive: true }); } await writeFile(testFile, warmupCode, "utf-8"); const detoxBinary = join(config.projectPath, config.detox.detoxBinary); const args = [ "test", "--configuration", detoxConfig, "--testNamePattern", "^mcp_action run$", testFile, ]; const result = await execa(detoxBinary, args, { cwd: config.projectPath, timeout: config.detox.testTimeoutMs, reject: false, }); // Cleanup try { await unlink(testFile); } catch { // Ignore } if (result.exitCode !== 0) { stateManager.updateDetox({ state: "failed" }); throw createError("DETOX_SESSION_FAILED", "Failed to start Detox session", { details: result.stderr || result.stdout, }); } stateManager.updateDetox({ state: "ready", sessionId, }); logger.info("detox", `Detox session started: ${sessionId}`); return { sessionId, configuration: detoxConfig, }; } catch (error) { stateManager.updateDetox({ state: "failed" }); throw error; } }
- src/mcp/schemas.ts:46-49 (schema)Zod schema defining the input parameters for the detox.session.start tool, including optional configuration and reuse flags.export const DetoxSessionStartInputSchema = z.object({ configuration: z.string().optional().describe("Detox configuration name. Defaults to config value."), reuse: z.boolean().optional().default(true).describe("Reuse existing session if available."), });
- src/mcp/server.ts:383-402 (registration)Registers the 'detox.session.start' tool in the MCP server, linking the schema and delegating execution to the startDetoxSession handler.server.tool( "detox.session.start", "Start a Detox testing session. Required before running UI actions.", DetoxSessionStartInputSchema.shape, async (args) => { try { const result = await startDetoxSession(args.configuration); return { content: [ { type: "text", text: JSON.stringify({ success: true, ...result }, null, 2), }, ], }; } catch (error) { return handleToolError(error); } } );