platform-apex-test-run: 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 platform-apex-test-run when the work involves:
sf apex run test workflows- 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 →
platform-apex-generate skill
- testing Agentforce agents →
agentforce-test skill
- testing LWC with Jest → experience-lwc-generate
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
platform-apex-generate skill 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 |
| API version 67.0 and higher without necessary access level checks |
Check failing SOQL/DML stack traces for CRUD/FLS access errors, using System.runAs with an assigned permission set when user-mode behavior is intended, or documenting a justified SYSTEM_MODE path when system access is required |
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 |
platform-apex-generate skill |
Code generation and repair |
| Create bulk / edge-case test data |
platform-data-manage |
Realistic test datasets |
| Deploy updated tests to org |
platform-metadata-deploy |
Deployment workflows |
| Inspect detailed runtime logs |
platform-apex-logs-debug |
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 |
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 |
1---2name: platform-apex-test-run3description: 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 platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate).4---5
6# platform-apex-test-run: Salesforce Test Execution & Coverage Analysis
7
8Use 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.
9
10## When This Skill Owns the Task
11
12Use `platform-apex-test-run` when the work involves:
13- `sf apex run test` workflows
14- Apex unit-test failures
15- code coverage analysis
16- identifying uncovered lines and missing test scenarios
17- structured test-fix loops for Apex code
18
19Delegate elsewhere when the user is:
20- writing or refactoring production Apex → `platform-apex-generate` skill
21- testing Agentforce agents → `agentforce-test` skill
22- testing LWC with Jest → [experience-lwc-generate](../experience-lwc-generate/SKILL.md)
23
24---
25
26## Required Context to Gather First
27
28Ask for or infer:
29- target org alias
30- desired test scope: single class, specific methods, suite, or local tests
31- coverage threshold expectation
32- whether the user wants diagnosis only or a test-fix loop
33- whether related test data factories already exist
34
35---
36
37## Recommended Workflow
38
39### 1. Discover test scope
40Identify:
41- existing test classes
42- target production classes
43- test data factories / setup helpers
44
45### 2. Run the smallest useful test set first
46Start narrow when debugging a failure; widen only after the fix is stable.
47
48### 3. Analyze results
49Focus on:
50- failing methods
51- exception types and stack traces
52- uncovered lines / weak coverage areas
53- whether failures indicate bad test data, brittle assertions, or broken production logic
54
55### 4. Run a disciplined fix loop
56When the issue is code or test quality:
57- delegate code fixes to `platform-apex-generate` skill when needed
58- add or improve tests
59- rerun focused tests before broader regression
60
61### 5. Improve coverage intentionally
62Cover:
63- positive path
64- negative / exception path
65- bulk path (251+ records where appropriate)
66- callout or async path when relevant
67
68---
69
70## High-Signal Rules
71
72| Rule | Rationale |
73|------|-----------|
74| Default to `SeeAllData=false` | Ensures test isolation; prevents reliance on org-specific data |
75| Every test must assert meaningful outcomes | Tests with no assertions prove nothing and give false confidence |
76| Test bulk behavior with 251+ records | Triggers process in batches of 200; 251 records crosses the boundary |
77| Use factories / `@TestSetup` when they improve clarity | Consistent data creation in one place; rolled back between test methods |
78| Pair `Test.startTest()` with `Test.stopTest()` for async | Ensures async operations (queueable, future) complete before assertions |
79| Do not hide flaky org dependencies inside tests | Prevents intermittent failures tied to org state |
80
81---
82
83## Gotchas
84
85| Issue | Resolution |
86|-------|------------|
87| Test passes locally but fails in CI org | Check for `SeeAllData=true` or undeclared dependencies on org-specific records |
88| Coverage drops unexpectedly after refactor | Run focused class-level tests first, then widen to `RunLocalTests` to confirm |
89| "Uncommitted work pending" error in callout test | DML and HTTP callouts cannot be mixed in the same test context without `Test.startTest()` wrapping |
90| Mock not taking effect in test | Ensure `Test.setMock()` is called before the code that makes the callout |
91| `@TestSetup` data missing in test method | `@TestSetup` data is committed per test method — re-query it; do not store in static variables |
92| API version 67.0 and higher without necessary access level checks | Check failing SOQL/DML stack traces for CRUD/FLS access errors, using System.runAs with an assigned permission set when user-mode behavior is intended, or documenting a justified `SYSTEM_MODE` path when system access is required |
93
94---
95
96## Output Format
97
98When finishing, report in this order:
991. **What tests were run**
1002. **Pass/fail summary**
1013. **Coverage result**
1024. **Root-cause findings**
1035. **Fix or next-run recommendation**
104
105Suggested shape:
106
107```text
108Test run: <scope>
109Org: <alias>
110Result: <passed / partial / failed>
111Coverage: <percent / key classes>
112Issues: <highest-signal failures>
113Next step: <fix class, add test, rerun scope, or widen regression>
114```
115
116---
117
118## Cross-Skill Integration
119
120| Need | Delegate to | Reason |
121|------|-------------|--------|
122| Fix production code or author test classes | `platform-apex-generate` skill | Code generation and repair |
123| Create bulk / edge-case test data | [platform-data-manage](../platform-data-manage/SKILL.md) | Realistic test datasets |
124| Deploy updated tests to org | [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md) | Deployment workflows |
125| Inspect detailed runtime logs | [platform-apex-logs-debug](../platform-apex-logs-debug/SKILL.md) | Deeper failure analysis |
126
127---
128
129## Reference File Index
130
131| File | When to read |
132|------|-------------|
133| `references/cli-commands.md` | All `sf apex run test` command flags, output formats, async execution, and coverage commands |
134| `references/test-patterns.md` | Test class templates — basic, bulk (251+), mock callout, and data factory patterns |
135| `references/testing-best-practices.md` | Core testing principles — AAA pattern, naming conventions, bulk, negative, and mock strategies |
136| `references/test-fix-loop.md` | Agentic test-fix loop implementation and failure analysis decision tree |
137| `references/mocking-patterns.md` | HttpCalloutMock, DML mocking, StubProvider, and selector mocking patterns |
138| `references/performance-optimization.md` | Techniques to reduce test execution time — DML mocking, SOQL mocking, loop optimizations |
139| `assets/basic-test.cls` | Template: standard test class with `@TestSetup`, positive / negative / bulk / edge-case methods |
140| `assets/bulk-test.cls` | Template: bulk test with 251+ records that crosses the 200-record trigger batch boundary |
141| `assets/mock-callout-test.cls` | Template: HTTP callout mock using `HttpCalloutMock` |
142| `assets/test-data-factory.cls` | Template: reusable `TestDataFactory` with create and insert helpers |
143| `assets/dml-mock.cls` | Template: `IDML` interface + `DMLMock` implementation for database-free unit tests |
144| `assets/stub-provider-example.cls` | Template: `StubProvider`-based dependency injection stub |
145| `scripts/parse-test-results.py` | Post-tool hook — parses `sf apex run test` JSON output and formats failures for the auto-fix loop |
146
147---
148
149## Score Guide
150
151| Score | Meaning |
152|---|---|
153| 108+ | strong production-grade test confidence |
154| 96–107 | good test suite with minor gaps |
155| 84–95 | acceptable but strengthen coverage / assertions |
156| < 84 | below standard; revise before relying on it |
forcedotcom