Validation Scripts

Validation scripts allow you to execute custom logic at specific points during the validation process. These global-level scripts provide hooks for setup, cleanup, reporting, and integration with external systems during validation workflows.

Validation Pipeline Execution

Configuration

{% @mermaid/diagram content="flowchart TD A[Validation Started] --> B[Fetch/Create Target Org] B --> C[Compute Impacted Packages] C --> D[Build Impacted Packages] D --> E[🔧 PRE-VALIDATION SCRIPT] E --> F[Deploy Packages to Target Org] F --> G[Run Apex Tests] G --> H[Validate Coverage] H --> I{Validation Result} I -->|Success| J[🏁 POST-VALIDATION SCRIPT] I -->|Failure| K[🏁 POST-VALIDATION SCRIPT] J --> L[Generate Reports] K --> L L --> M[Cleanup Resources]

style E fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style J fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
style K fill:#ffebee,stroke:#c62828,stroke-width:2px" %}

Add script paths to your sfdx-project.json file:

{
  "plugins": {
    "sfp": {
      "validateScripts": {
        "preValidation": "./scripts/pre-validate.sh",
        "postValidation": "./scripts/post-validate.sh"
      }
    }
  }
}

Script Arguments

Scripts receive three arguments in this order:

1. Context File Path - Absolute path to temporary JSON file containing validation context

2. Target Org - Username of the target organization for validation

3. Hub Org - Username of the hub organization (empty string "" if not available)

# Example script invocation:
./scripts/pre-validate.sh /tmp/sfp-validate-pre-1234567890.json [email protected] [email protected]

Context Data Structure

Pre-Validation Context

The context file contains information about packages ready for validation:

{
  "phase": "pre-validation",
  "targetOrg": "scratch-org-username",
  "hubOrg": "devhub-username",
  "validationMode": "thorough",
  "packages": [
    {
      "name": "core-crm",
      "version": "2.1.0.NEXT", 
      "type": "source",
      "isChanged": true
    }
  ]
}

Post-Validation Context

The context file includes all pre-validation data plus validation results:

{
  "phase": "post-validation",
  "targetOrg": "scratch-org-username",
  "hubOrg": "devhub-username",
  "validationMode": "thorough",
  "packages": [/* same as pre-validation */],
  "validationResults": {
    "status": "success",
    "deployedPackages": ["core-crm", "shared-utils"],
    "failedPackages": [],
    "error": undefined
  }
}

Example Scripts

Pre-Validation Script

#!/bin/bash
set -e

CONTEXT_FILE="$1"
TARGET_ORG="$2"
HUB_ORG="$3"

echo "🔧 Pre-validation setup starting..."

# Parse context
PACKAGES=$(cat "$CONTEXT_FILE" | jq -r '.packages[].name' | tr '\n' ' ')
VALIDATION_MODE=$(cat "$CONTEXT_FILE" | jq -r '.validationMode')

echo "📦 Packages to validate: $PACKAGES"
echo "🎯 Validation mode: $VALIDATION_MODE"
echo "🏢 Target org: $TARGET_ORG"

# Custom setup logic
if [ "$VALIDATION_MODE" = "thorough" ]; then
    echo "🔧 Setting up comprehensive validation environment..."
    # Setup test data, configure external systems, etc.
fi

# Example: Notify external systems
curl -X POST "https://internal-api.company.com/validation/started" \
     -H "Content-Type: application/json" \
     -d "{\"packages\": \"$PACKAGES\", \"targetOrg\": \"$TARGET_ORG\"}"

echo "✅ Pre-validation setup completed"

Post-Validation Script

#!/bin/bash
CONTEXT_FILE="$1"
TARGET_ORG="$2"
HUB_ORG="$3"

echo "🏁 Post-validation processing starting..."

# Parse results
STATUS=$(cat "$CONTEXT_FILE" | jq -r '.validationResults.status')
DEPLOYED=$(cat "$CONTEXT_FILE" | jq -r '.validationResults.deployedPackages[]' | tr '\n' ' ')
FAILED=$(cat "$CONTEXT_FILE" | jq -r '.validationResults.failedPackages[]' | tr '\n' ' ')

echo "📊 Validation status: $STATUS"
echo "✅ Deployed packages: $DEPLOYED"

if [ "$STATUS" = "failed" ]; then
    echo "❌ Failed packages: $FAILED"
    ERROR=$(cat "$CONTEXT_FILE" | jq -r '.validationResults.error // "Unknown error"')
    echo "🔍 Error details: $ERROR"
    
    # Notify failure
    curl -X POST "https://internal-api.company.com/validation/failed" \
         -H "Content-Type: application/json" \
         -d "{\"error\": \"$ERROR\", \"failedPackages\": \"$FAILED\"}"
else
    echo "🎉 Validation successful!"
    
    # Notify success  
    curl -X POST "https://internal-api.company.com/validation/success" \
         -H "Content-Type: application/json" \
         -d "{\"deployedPackages\": \"$DEPLOYED\"}"
fi

echo "✅ Post-validation processing completed"

Error Handling & Behavior

Script Type	Failure Behavior	Timeout	Use Cases
Pre-validation	Halts validation process	30 minutes	Setup test data, configure environments, validate prerequisites
Post-validation	Logged as warning, validation continues	30 minutes	Cleanup resources, send notifications, generate reports

Best Practices

• Make scripts executable: chmod +x scripts/pre-validate.sh

• Use set -e: Exit on errors to ensure proper failure handling

• Parse JSON safely: Use jq for reliable JSON parsing

• Handle missing data: Check if fields exist before using them

• Log clearly: Scripts appear in validation logs with CI/CD folding

• Keep scripts fast: Remember the 30-minute timeout limit

• Test locally: Validate script behavior before committing

Common Use Cases

Pre-Validation Scripts

• Set up test data specific to validation scenarios

• Configure external API endpoints for testing

• Validate prerequisites (licenses, feature flags, etc.)

• Initialize monitoring or logging for the validation process

Post-Validation Scripts

• Clean up test data created during validation

• Send notifications to Slack, Teams, or other systems

• Generate custom reports or metrics

• Update external tracking systems with validation results

• Archive validation artifacts or logs