Test-Driven Development

Iterate on Apex code with fast feedback by running aer test --watch. Watch mode keeps the test runner alive, re-executes suites when files change, and surfaces failures immediately so you can adjust your code or tests before context switches pile up.

Start watch mode

aer test force-app/main/default \
  --watch

The command scans the supplied directories for Apex files and starts an incremental test loop:

• Compiles the project once to seed the in-memory schema and package cache.
• Watches Apex source, schema files, and package definitions inside the provided paths.
• Re-runs the affected tests after every successful compile.

Runs outside watch mode are also faster the second time. The parsed and type-checked program is saved as a workspace image keyed by the source contents, so a rerun over unchanged sources skips parsing, semantic analysis, type checking, and symbol resolution. Runs with --package and --package-dir use the same cache. Use aer cache info to see what is stored and aer cache clean to discard it.

Press Ctrl+C when you are ready to stop the session.

Focus on a slice of work

Combine --watch with existing flags to keep the loop tight:

aer test force-app/main/default \
  --watch \
  --filter OrderService

• --filter narrows execution to tests that contain the supplied substrings.
• --suite runs the classes named by an ApexTestSuite in your source.
• --package or --package-dir lets you load managed packages so watch mode runs against realistic dependencies.
• --schema or --no-auto-schema controls whether watch mode bootstraps a local schema from source.

Update tests first, save the file, and aer recompiles before running the focused subset, giving you near-instant confirmation that the new expectations fail.

Keep the loop fast

Follow these cadence tips when practicing test-driven development:

• Write or modify one test at a time and commit the file before changing implementation.
• Keep the watch output visible so you notice regressions the moment they land.
• Use --quiet once the loop is stable to hide passing output and highlight failures.
• Pair --watch with --verbose when you need quick “printf” debugging; the flag streams System.debug output so you can inspect values between runs.
• Store temporary artifacts (profiles, traces) outside your repo if you combine watch mode with --profile or --trace.
• Send SIGUSR1 to a running aer test process (kill -USR1 <pid>) to print a one-line status summary to stderr without waiting for the periodic progress output. During setup it reports the current phase and elapsed time; once tests start it reports test counts.

When the test goes green, repeat the cycle: refactor with confidence, save, and let watch mode validate the change. The tight feedback loop keeps you in flow while you grow Apex coverage.