/platform-apex-test-run

name: platform-apex-test-run
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 platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate)."
metadata:
  version: "1.2"
  domains: ["Platform"]
  relatedSkills:
    - "agentforce-test"
    - "experience-lwc-generate"
    - "platform-apex-generate"
    - "platform-apex-logs-debug"
    - "platform-data-manage"
    - "platform-metadata-deploy"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["python3"]
      semver: ">=3.10.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

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](../experience-lwc-generate/SKILL.md)

---

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: 1. **What tests were run** 2. **Pass/fail summary** 3. **Coverage result** 4. **Root-cause findings** 5. **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](../platform-data-manage/SKILL.md) | Realistic test datasets | | Deploy updated tests to org | [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md) | Deployment workflows | | Inspect detailed runtime logs | [platform-apex-logs-debug](../platform-apex-logs-debug/SKILL.md) | 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` |