Spotlight testing

Spotlight testing syncs one workspace back to your repository root so you can test from the root directory instead of the workspace directory.

Use Spotlight testing when your project needs the root checkout, a fixed local resource, or one heavy local stack that should stay running while you switch between workspace changes.

Spotlight testing or run scripts

Use normal run scripts when each workspace can run its own copy of the project. Run scripts are the default testing path because each workspace gets its own process, paths, and allocated ports.

Use Spotlight testing when the project needs to run from the repository root, or when running one full stack per workspace would be too expensive. Spotlight testing is a good fit for:

• Directory-dependent applications that assume they run from the repository root.
• Projects with expensive initial builds that can reuse build artifacts in the repository root.
• Apps that depend on a fixed port, one local database, or another single shared local resource.
• Docker-heavy or microservice projects where running one full stack per workspace would consume too much CPU, memory, disk, or battery.
• Apps that take a long time to start but can hot reload quickly once the root process is running.
• Dev scripts with hard-coded local values that are difficult to make workspace-specific.

Spotlight testing only tests one workspace at a time. If your project only needs to prevent multiple run scripts from sharing one port or database, consider nonconcurrent run script mode first.

Cloud workspaces are another option when local resource usage is the main problem. Spotlight is most useful when you want to keep agents working in local workspaces while only one local application stack runs from the repository root.

Configure Spotlight testing

You can configure Spotlight testing in Conductor or in a settings file:

• In the app, open Settings, select the project, and turn on Use spotlight testing.
• In the repository, add spotlight_testing to .conductor/settings.toml when the same testing workflow should be shared with teammates.

Use this repository configuration when every teammate should test this project from the repository root:

"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"

spotlight_testing = true

Commit .conductor/settings.toml when every teammate should use Spotlight testing for the repository. For settings file locations and precedence, see User and project settings.

Spotlight testing only changes testing for that project. Other projects can keep using normal run scripts and workspace isolation.

Spotlight a workspace

Before you start Spotlight, run your application from the repository root in Conductor. For example, start the Docker stack, dev server, or other long-running process from the root checkout.

Then click the Spotlight button from the workspace you want to test. Conductor copies that workspace's tracked changes back to the repository root so the root process can run them.

When you turn Spotlight mode off, Conductor restores the original repository root state.

While Spotlight is on:

• The project runs from the repository root, not the workspace directory.
• Tracked workspace changes are swapped into the root as the workspace changes.
• Switching Spotlight to another workspace replaces the root with that workspace's tracked changes.
• Existing root build caches and long-running processes can keep hot reloading instead of starting from scratch.

You can keep creating branches, chatting with agents, and preparing pull requests from separate workspaces. Spotlight only changes which workspace's tracked changes are active in the root process.

How it works

Spotlight testing watches your workspace for changes. When files change, Conductor creates a checkpoint commit of your workspace and checks it out in the repository root.

Only files tracked in git are copied back to the repository root. Build artifacts such as node_modules are not copied.

Spotlight testing is a one-way sync. Changes in the repository root are not copied back to your workspace. Edit files in the workspace so Conductor can sync them to the repository root.

Troubleshooting

If Spotlight cannot start, check whether the workspace or repository root has a rebase or merge in progress.

Finish the operation with git rebase --continue or git merge --continue, or cancel it with git rebase --abort or git merge --abort. Run the command in the directory that has the pending operation.