Feature: Add validate_only option for Snowfakery & GenerateAndLoadData Task

[aditya-balachander]

Overview

This PR introduces two improvements to CumulusCI's data loading functionality:

1. Fixed a bug where required field validation was not properly reporting errors
2. Added a new validate_only option to the snowfakery task to validate mapping files against org schemas without loading data

---

1. Bug Fix: Required Field Validation

Problem

The required field validation in mapping_parser.py was not properly blocking validation when required fields were missing. The issue was in the validate_and_inject_namespace() method, which called check_required() but ignored its return value, causing validation to silently pass even when required fields were absent.

Previous Code (Buggy)

# In validate_and_inject_namespace()
if is_load:
    # Show warning logs for unspecified required fields
    self.check_required(describe)  # BUG: Return value ignored!
    # Validation continues even if required fields are missing

The check_required() method would return False when required fields were missing, but the calling code never checked this return value, so validation would proceed as if everything was fine.

Fixed Code

# In validate_and_inject_namespace()
if is_load:
    # Check for unspecified required fields
    required_fields_present = self.check_required(describe, validation_result)
    # Only block if drop_missing is False, otherwise just warn
    if not required_fields_present and not drop_missing:
        return False

Now the code:

1. Captures the return value from check_required()
2. Adds errors to the validation_result object (when provided)
3. Returns False to block validation if required fields are missing (unless drop_missing=True)

---

2. New Feature: validate_only Option

What It Does

The validate_only option allows users to validate their data generation recipes and mapping files against the target org's schema without actually loading any data. This is specifically done for the Snowfakery Task as a part of TD-0268770

How It Works

When validate_only=True:

1. Data Generation: Generates minimal data (1 record) to create the mapping structure
2. Mapping Validation: Validates the mapping against the org schema using Salesforce Describe API
3. Error Collection: Collects all validation errors and warnings without throwing exceptions
4. Result Reporting: Returns a ValidationResult object with detailed errors and warnings
5. No Data Load: Skips the actual data loading step entirely

Updated Tasks

Snowfakery Task (snowfakery.py):

• Added validate_only option to task options
• Added _run_validation() method that generates minimal data and validates
• Routes to validation flow when validate_only=True in _run_task()

GenerateAndLoadData Task (generate_and_load_data.py):

• Added validate_only option to task options
• Added _run_validation() method
• Added _validate_mapping() helper method with user-friendly logging

Usage Examples

Example 1: Snowfakery with Invalid Recipe (Missing Required Field)

cci task run snowfakery \
  --recipe testing_invalid.yml \
  --validate_only True \
  --org dev

Output:

[10/14/25 16:20:47] Beginning task: Snowfakery                                                                                                                                                               
                    As user: epic.out.eec9075f4f12@orgfarm.salesforce.com                                                                                                                                    
                    In org: 00DSB00000cZUOk                                                                                                                                                                  
                                                                                                                                                                                                             
[10/14/25 16:20:48] Beginning task: GenerateAndLoadDataFromYaml                                                                                                                                              
                    As user: epic.out.eec9075f4f12@orgfarm.salesforce.com                                                                                                                                    
                    In org: 00DSB00000cZUOk                                                                                                                                                                  
                                                                                                                                                                                                             
                    Beginning task: GenerateDataFromYaml                                                                                                                                                     
                                                                                                                                                                                                             
                    Generating batch 0 with 1                                                                                                                                                                
                    Generated batch                                                                                                                                                                          
                    Validating mapping file: .../temp_mapping.yml                                                               
[10/14/25 16:20:50] One or more required fields are missing for loading on Account :{'Name'}                                                                                                                 
                                                                                                                                                                                                             
                    == Validation Failed ==
                    Errors: 1

Example 2: Snowfakery with Valid Recipe

cci task run snowfakery \
  --recipe testing_valid.yml \
  --validate_only True \
  --org dev

Output:

[10/14/25 16:19:46] Beginning task: Snowfakery                                                                                                                                                               
                    As user: epic.out.eec9075f4f12@orgfarm.salesforce.com                                                                                                                                    
                    In org: 00DSB00000cZUOk                                                                                                                                                                  
                                                                                                                                                                                                             
[10/14/25 16:19:47] Beginning task: GenerateAndLoadDataFromYaml                                                                                                                                              
                    As user: epic.out.eec9075f4f12@orgfarm.salesforce.com                                                                                                                                    
                    In org: 00DSB00000cZUOk                                                                                                                                                                  
                                                                                                                                                                                                             
                    Beginning task: GenerateDataFromYaml                                                                                                                                                     
                                                                                                                                                                                                             
                    Generating batch 0 with 1                                                                                                                                                                
                    Generated batch                                                                                                                                                                          
                    Validating mapping file: .../temp_mapping.yml                                                               
[10/14/25 16:19:49]                                                                                                                                                                                          
                    == Validation Successful ==  

Example 3: Normal Load (validate_only=False)

cci task run snowfakery \
  --recipe testing_valid.yml \
  --validate_only False \
  --org dev

Output:

[10/14/25 16:21:47] Beginning task: Snowfakery                                                                                                                                                               
                    As user: epic.out.eec9075f4f12@orgfarm.salesforce.com                                                                                                                                    
                    In org: 00DSB00000cZUOk                                                                                                                                                                  
                                                                                                                                                                                                             
                    Working directory is /var/folders/ws/4tz9ymyx1sbd999w1h0vk9ym0000gn/T/tmpd62ht2qf                                                                                                        
[10/14/25 16:21:48] Beginning task: GenerateAndLoadDataFromYaml                                                                                                                                              
                    As user: epic.out.eec9075f4f12@orgfarm.salesforce.com                                                                                                                                    
                    In org: 00DSB00000cZUOk                                                                                                                                                                  
                                                                                                                                                                                                             
                    Beginning task: GenerateDataFromYaml                                                                                                                                                     
                                                                                                                                                                                                             
                    Generating batch 0 with 1                                                                                                                                                                
                    Generated batch                                                                                                                                                                          
                    Beginning task: LoadData                                                                                                                                                                 
                    As user: epic.out.eec9075f4f12@orgfarm.salesforce.com                                                                                                                                    
                    In org: 00DSB00000cZUOk                                                                                                                                                                  
                                                                                                                                                                                                             
[10/14/25 16:21:51] Running step: Insert Account                                                                                                                                                             
                    Creating insert Operation for Account using smart                                                                                                                                        
                    Prepared 2 rows for insert to Account.                                                                                                                                                   
[10/14/25 16:21:52]                                                                                                                                                                                          
                     == Results ==                                                                                                                                                                           
                           Account: 2 successes, 0 errors                                                                                                                                                    
                    ☃ Snowfakery created 1 iterations in 5s.

[jkasturi-sf]

Looks good