Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-test

agentforce-test

Flagged

Write, run, and analyze structured test suites for Agentforce agents — functional AND security. TRIGGER when: user writes or modifies test spec YAML (AiEvaluationDefinition); runs sf agent test create, run, run-eval, or results commands; asks about test coverage strategy, metric selection, or custom evaluations; interprets test results or diagnoses test failures; asks about batch testing, regression suites, or CI/CD test integration; requests security testing, OWASP LLM Top 10, red-teaming, penetration testing, prompt-injection tests, a security grade, or a vulnerability assessment of an agent. DO NOT TRIGGER when: user creates, modifies, previews, or debugs .agent files (use agentforce-generate); deploys or publishes agents; writes Agent Script code; uses sf agent preview for development iteration; analyzes production session traces (use agentforce-observe); performs a static safety review of .agent file content (use agentforce-generate Section 15).

references/action-execution.md

View on GitHub
# Action Execution — Full Reference

Execute individual Agentforce actions directly against a Salesforce org for testing and debugging.

## Safety Gate (Required)

Before executing ANY action, perform these checks:

### 1. Org Safety Check
Verify the target org is not a production org:
```bash
sf data query --json -q "SELECT IsSandbox FROM Organization" -o <org-alias>
```
If `IsSandbox` is `false`, display a prominent warning:
```text
WARNING: Target org is a PRODUCTION org. Running actions against production
can modify real data. Proceed with extreme caution.
```
Ask for explicit confirmation before proceeding on production orgs.

### 2. DML Safety Check
If the action target is a Flow or Apex that performs write operations (CREATE, UPDATE, DELETE),
warn the user and recommend using a sandbox or scratch org first.

### 3. Input Validation
- Do NOT include real PII (SSN, credit card numbers, real email addresses) in test inputs
- Use synthetic test data: `test@example.com`, `000-00-0000`, `4111111111111111`
- If the user provides what appears to be real PII, warn them and suggest synthetic alternatives

## Setup: Authenticate the Org

```bash
# Ensure org is authenticated
sf org display --json -o <org-alias>

# If not authenticated, login first
sf org login web --json --alias <org-alias>
```

All REST calls below use `sf api request rest`, which authenticates at the
transport layer using the CLI's stored credentials. No access token is ever
extracted or exposed.

## Execute a Flow Action

```bash
sf api request rest "/services/data/v63.0/actions/custom/flow/Get_Order_Status" \
  --method POST \
  --body '{"inputs": [{"orderId": "00190000023XXXX"}]}' \
  -o <org-alias>
```

## Execute an Apex Action

```bash
sf api request rest "/services/data/v63.0/actions/custom/apex/OrderProcessor" \
  --method POST \
  --body '{"inputs": [{"orderId": "00190000023XXXX", "actionType": "cancel", "reason": "Customer request"}]}' \
  -o <org-alias>
```

## Execute with JSON Input File

For complex inputs, write a JSON file and pass it to `sf api request rest` with `--file`:

```bash
cat > /tmp/action-inputs.json << 'EOF'
{
  "inputs": [
    {
      "orderId": "00190000023XXXX",
      "lineItems": [
        {"productId": "01tXX0000008cXX", "quantity": 2, "discount": 0.1}
      ]
    }
  ]
}
EOF

sf api request rest "/services/data/v63.0/actions/custom/flow/Process_Return" \
  --method POST \
  --file /tmp/action-inputs.json \
  -o <org-alias>
```

## Pretty-Print Response

Pipe the JSON response through `jq`:

```bash
sf api request rest "/services/data/v63.0/actions/custom/flow/Get_Order_Status" \
  --method POST \
  --body '{"inputs": [{"orderId": "00190000023XXXX"}]}' \
  -o <org-alias> | jq .
```

## Target Protocols

### Flow Actions (`flow://`)

Executes an Autolaunched Flow via REST API:

```text
POST /services/data/v63.0/actions/custom/flow/{flowApiName}
```

Example request body:
```json
{
  "inputs": [
    {
      "orderId": "00190000023XXXX",
      "includeDetails": true
    }
  ]
}
```

Example response:
```json
{
  "actionName": "Get_Order_Status",
  "errors": [],
  "isSuccess": true,
  "outputValues": {
    "orderStatus": "Shipped",
    "trackingNumber": "1Z999AA10123456784",
    "estimatedDelivery": "2024-03-15"
  }
}
```

### Apex Actions (`apex://`)

Executes an @InvocableMethod via REST API:

```text
POST /services/data/v63.0/actions/custom/apex/{className}
```

The Apex class must have exactly one method annotated with `@InvocableMethod`.

Example request body:
```json
{
  "inputs": [
    {
      "orderId": "00190000023XXXX",
      "actionType": "cancel"
    }
  ]
}
```

Example response:
```json
{
  "actionName": "OrderProcessor",
  "errors": [],
  "isSuccess": true,
  "outputValues": [
    {
      "success": true,
      "message": "Order cancelled successfully",
      "refundAmount": 299.99
    }
  ]
}
```

## Integration Testing

### Test Flow Pattern

1. **Prepare test data**:
```bash
RECORD_ID=$(sf data create record --json -s Account \
  -v "Name='Test Account' Type='Customer'" \
  -o myorg | jq -r '.result.id')
```

2. **Execute action**:
```bash
sf api request rest "/services/data/v63.0/actions/custom/flow/Update_Account" \
  --method POST \
  --body "{\"inputs\": [{\"accountId\": \"$RECORD_ID\", \"status\": \"Active\"}]}" \
  -o myorg | jq .
```

3. **Verify results**:
```bash
sf data query --json \
  --query "SELECT Name, Status__c FROM Account WHERE Id = '$RECORD_ID'" \
  -o myorg
```

4. **Clean up**:
```bash
sf data delete record --json -s Account -i $RECORD_ID -o myorg
```

## Debugging

### Retrieve Apex Debug Logs

After executing an Apex action, fetch the most recent debug log:

```bash
sf apex log get --json --number 1 -o <org-alias>
```

### Inspect Available Actions

List all available custom actions to verify deployment:

```bash
# List all Flow actions
sf api request rest "/services/data/v63.0/actions/custom/flow" \
  -o <org-alias> | jq '.actions[].name'

# List all Apex actions
sf api request rest "/services/data/v63.0/actions/custom/apex" \
  -o <org-alias> | jq '.actions[].name'
```

## Error Handling

### Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `NOT_FOUND` | Flow/Apex not found | Verify target name and deployment |
| `INVALID_INPUT` | Input parameter mismatch | Check required inputs in Flow/Apex |
| `INSUFFICIENT_ACCESS` | Permission issue | Verify user permissions |
| `LIMIT_EXCEEDED` | Governor limit hit | Reduce batch size or optimize logic |
| `INVALID_SESSION_ID` | Auth expired | Re-authenticate: `sf org login web` |

### Best Practices

- Check `isSuccess` in the response before processing outputs
- Verify ID format (15 or 18 characters) before sending
- Use `jq` to extract specific fields from responses
- Create and clean up test data to avoid polluting the org
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall