running-apex-tests
forcedotcom/sf-skills
Run Apex tests, analyze coverage, and fix failures with structured test-fix loops.
What is running-apex-tests?
Execute Apex unit tests, check code coverage, diagnose failures, and manage disciplined test-fix workflows in Salesforce orgs. Use this skill when running tests, checking coverage, fixing failing tests, or working with *Test.cls files.
- Execute Apex tests via sf apex run test with configurable scope (single class, methods, suite, or local tests)
- Analyze code coverage results and identify uncovered lines and weak coverage areas
- Diagnose test failures with exception types, stack traces, and root-cause analysis
- Run structured test-fix loops: narrow debugging first, then widen regression testing
- Enforce test quality rules: SeeAllData=false, meaningful assertions, bulk testing (251+ records), and async test wrapping
How to install running-apex-tests
npx skills add https://github.com/forcedotcom/sf-skills --skill running-apex-tests- Salesforce CLI (sf) installed and authenticated to target org
- Target org alias configured
- Existing Apex test classes (*Test.cls or *_Test.cls files) or ability to author them
How to use running-apex-tests
- 1.Gather required context: target org alias, test scope (single class, methods, suite, or local tests), coverage threshold, and whether diagnosis or test-fix loop is needed
- 2.Discover test scope by identifying existing test classes, target production classes, and test data factories
- 3.Run the smallest useful test set first using sf apex run test with focused scope
- 4.Analyze results: failing methods, exception types, stack traces, uncovered lines, and coverage gaps
- 5.Execute a disciplined fix loop: delegate code fixes to generating-apex skill if needed, add or improve tests, rerun focused tests before broader regression
- 6.Report findings in order: test scope run, pass/fail summary, coverage result, root-cause findings, and next-step recommendation
Use cases
- Debug a failing Apex test by running focused tests, analyzing the exception, and iterating fixes
- Improve code coverage by identifying uncovered lines and authoring targeted test scenarios
- Validate bulk behavior by running tests with 251+ records to cross the 200-record trigger batch boundary
- Verify test isolation by confirming SeeAllData=false and no undeclared org-specific dependencies
- Manage a test-fix loop: run tests, delegate code fixes to generating-apex skill, add tests, rerun focused tests before regression
- Salesforce developers writing and maintaining Apex unit tests
- QA engineers validating test coverage and test quality before deployment
- DevOps engineers running test suites in CI/CD pipelines
- Technical leads enforcing test discipline and coverage standards
running-apex-tests FAQ
Use running-apex-tests for test execution, failure diagnosis, and coverage analysis. Delegate to generating-apex when you need to write or refactor production Apex code or author new test classes.
Start with the smallest useful test set when debugging a failure (single test method or class). Widen to RunLocalTests only after the fix is stable to confirm no regressions.
Salesforce triggers batch DML in groups of 200 records. Testing with 251+ records ensures your code handles the boundary condition where a second batch is triggered.
Use SeeAllData=false (default), avoid undeclared dependencies on org-specific records, use @TestSetup or test data factories for consistent data creation, and pair Test.startTest() with Test.stopTest() for async operations.
Check for SeeAllData=true, undeclared dependencies on org-specific records, or mixed DML and HTTP callouts without proper Test.startTest() wrapping. Run focused class-level tests first, then widen to RunLocalTests.
Full instructions (SKILL.md)
Source of truth, from forcedotcom/sf-skills.
name: running-apex-tests description: "Apex test execution, coverage analysis, and test-fix loops with 120-point scoring. Use when the user needs to run Apex tests, check code coverage, fix failing tests, or work with *Test.cls / *_Test.cls files. TRIGGER when: user runs Apex tests, checks code coverage, fixes failing tests, or touches *Test.cls / *_Test.cls files. DO NOT TRIGGER when: writing Apex production code (use generating-apex), Agentforce agent testing (use testing-agentforce), or Jest/LWC tests (use generating-lwc-components)." metadata: version: "1.1"
running-apex-tests: Salesforce Test Execution & Coverage Analysis
Use this skill when the user needs Apex test execution and failure analysis: running tests, checking coverage, interpreting failures, improving coverage, and managing a disciplined test-fix loop for Salesforce code.
When This Skill Owns the Task
Use running-apex-tests when the work involves:
sf apex run testworkflows- Apex unit-test failures
- code coverage analysis
- identifying uncovered lines and missing test scenarios
- structured test-fix loops for Apex code
Delegate elsewhere when the user is:
- writing or refactoring production Apex →
generating-apexskill - testing Agentforce agents →
testing-agentforceskill - testing LWC with Jest → generating-lwc-components
Required Context to Gather First
Ask for or infer:
- target org alias
- desired test scope: single class, specific methods, suite, or local tests
- coverage threshold expectation
- whether the user wants diagnosis only or a test-fix loop
- whether related test data factories already exist
Recommended Workflow
1. Discover test scope
Identify:
- existing test classes
- target production classes
- test data factories / setup helpers
2. Run the smallest useful test set first
Start narrow when debugging a failure; widen only after the fix is stable.
3. Analyze results
Focus on:
- failing methods
- exception types and stack traces
- uncovered lines / weak coverage areas
- whether failures indicate bad test data, brittle assertions, or broken production logic
4. Run a disciplined fix loop
When the issue is code or test quality:
- delegate code fixes to
generating-apexskill when needed - add or improve tests
- rerun focused tests before broader regression
5. Improve coverage intentionally
Cover:
- positive path
- negative / exception path
- bulk path (251+ records where appropriate)
- callout or async path when relevant
High-Signal Rules
| Rule | Rationale |
|---|---|
Default to SeeAllData=false | Ensures test isolation; prevents reliance on org-specific data |
| Every test must assert meaningful outcomes | Tests with no assertions prove nothing and give false confidence |
| Test bulk behavior with 251+ records | Triggers process in batches of 200; 251 records crosses the boundary |
Use factories / @TestSetup when they improve clarity | Consistent data creation in one place; rolled back between test methods |
Pair Test.startTest() with Test.stopTest() for async | Ensures async operations (queueable, future) complete before assertions |
| Do not hide flaky org dependencies inside tests | Prevents intermittent failures tied to org state |
Gotchas
| Issue | Resolution |
|---|---|
| Test passes locally but fails in CI org | Check for SeeAllData=true or undeclared dependencies on org-specific records |
| Coverage drops unexpectedly after refactor | Run focused class-level tests first, then widen to RunLocalTests to confirm |
| "Uncommitted work pending" error in callout test | DML and HTTP callouts cannot be mixed in the same test context without Test.startTest() wrapping |
| Mock not taking effect in test | Ensure Test.setMock() is called before the code that makes the callout |
@TestSetup data missing in test method | @TestSetup data is committed per test method — re-query it; do not store in static variables |
Output Format
When finishing, report in this order:
- What tests were run
- Pass/fail summary
- Coverage result
- Root-cause findings
- Fix or next-run recommendation
Suggested shape:
Test run: <scope>
Org: <alias>
Result: <passed / partial / failed>
Coverage: <percent / key classes>
Issues: <highest-signal failures>
Next step: <fix class, add test, rerun scope, or widen regression>
Cross-Skill Integration
| Need | Delegate to | Reason |
|---|---|---|
| Fix production code or author test classes | generating-apex skill | Code generation and repair |
| Create bulk / edge-case test data | handling-sf-data | Realistic test datasets |
| Deploy updated tests to org | deploying-metadata | Deployment workflows |
| Inspect detailed runtime logs | debugging-apex-logs | Deeper failure analysis |
Reference File Index
| File | When to read |
|---|---|
references/cli-commands.md | All sf apex run test command flags, output formats, async execution, and coverage commands |
references/test-patterns.md | Test class templates — basic, bulk (251+), mock callout, and data factory patterns |
references/testing-best-practices.md | Core testing principles — AAA pattern, naming conventions, bulk, negative, and mock strategies |
references/test-fix-loop.md | Agentic test-fix loop implementation and failure analysis decision tree |
references/mocking-patterns.md | HttpCalloutMock, DML mocking, StubProvider, and selector mocking patterns |
references/performance-optimization.md | Techniques to reduce test execution time — DML mocking, SOQL mocking, loop optimizations |
assets/basic-test.cls | Template: standard test class with @TestSetup, positive / negative / bulk / edge-case methods |
assets/bulk-test.cls | Template: bulk test with 251+ records that crosses the 200-record trigger batch boundary |
assets/mock-callout-test.cls | Template: HTTP callout mock using HttpCalloutMock |
assets/test-data-factory.cls | Template: reusable TestDataFactory with create and insert helpers |
assets/dml-mock.cls | Template: IDML interface + DMLMock implementation for database-free unit tests |
assets/stub-provider-example.cls | Template: StubProvider-based dependency injection stub |
hooks/scripts/parse-test-results.py | Post-tool hook — parses sf apex run test JSON output and formats failures for the auto-fix loop |
Score Guide
| Score | Meaning |
|---|---|
| 108+ | strong production-grade test confidence |
| 96–107 | good test suite with minor gaps |
| 84–95 | acceptable but strengthen coverage / assertions |
| < 84 | below standard; revise before relying on it |
Related skills
More from forcedotcom/sf-skills and the wider catalog.
running-code-analyzer
Scan Salesforce code for security, performance, and quality violations across all engines (PMD, ESLint, CPD, RetireJS, Flow, SFGE, ApexGuru).
searching-media
Route and execute media searches across Salesforce CMS, Data 360, and other sources.
segmenting-datacloud
Create, publish, and troubleshoot Salesforce Data Cloud segments and calculated insights.
switching-org
Switch the active Salesforce org for CLI commands using the Salesforce CLI.
testing-agentforce
Write, run, and analyze structured test suites for Agentforce agents.
uplifting-components-to-slds2
Migrate Lightning Web Components from SLDS 1 to SLDS 2 using the SLDS linter and structured violation fixes.