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

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 [e-mail] [e-mail]

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": "NEXT",
      "type": "source",
      "isChanged": true
    }
  ]
}

Only name carries real per-package data. version, type and isChanged are currently emitted as the fixed values NEXT, source and true for every entry, so a script should not branch on them.

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