""" Variable parsing and substitution utilities for data-driven testing. This module provides functions for: - Validating variable names (snake_case convention) - Extracting variables from text using {{variable_name}} syntax - Substituting variables with their values - Validating that all used variables are defined Variable Syntax: - Local variables: {{variable_name}} - Global variables: {{global.variable_name}} Variable Naming Convention: - Only lowercase letters and underscores allowed - Must start and end with a letter - No consecutive underscores """ import re from typing import Dict, List, Tuple, Set, Any, Optional # Regex patterns # Local variable: {{variable_name}} where variable_name is lowercase letters and underscores LOCAL_VAR_PATTERN = r'\{\{([a-z][a-z_]*[a-z]|[a-z])\}\}' # Global variable: {{global.variable_name}} GLOBAL_VAR_PATTERN = r'\{\{global\.([a-z][a-z_]*[a-z]|[a-z])\}\}' # Variable name validation: only lowercase letters and underscores VARIABLE_NAME_PATTERN = r'^[a-z][a-z_]*[a-z]$|^[a-z]$' def validate_variable_name(name: str) -> Tuple[bool, str]: """ Validate variable name follows snake_case convention. Rules: - Only lowercase letters (a-z) and underscores allowed - Must start with a letter - Must end with a letter - No consecutive underscores - Single letter names are allowed Args: name: The variable name to validate Returns: Tuple of (is_valid, error_message) - is_valid: True if the name is valid - error_message: Empty string if valid, otherwise describes the issue """ if not name: return False, "Variable name cannot be empty" # Check for invalid characters if not re.match(r'^[a-z_]+$', name): return False, "Variable name must contain only lowercase letters (a-z) and underscores" # Check starts with letter if name[0] == '_': return False, "Variable name must start with a letter" # Check ends with letter if name[-1] == '_': return False, "Variable name must end with a letter" # Check for consecutive underscores if '__' in name: return False, "Variable name cannot have consecutive underscores" return True, "" def extract_variables(text: str) -> Tuple[Set[str], Set[str]]: """ Extract local and global variable names from text. Finds all occurrences of {{variable_name}} and {{global.variable_name}} patterns in the text and returns the variable names as sets. Args: text: The text to search for variables Returns: Tuple of (local_variables, global_variables) as sets of variable names """ if not text: return set(), set() # Find all local variables local_vars = set(re.findall(LOCAL_VAR_PATTERN, text)) # Find all global variables global_vars = set(re.findall(GLOBAL_VAR_PATTERN, text)) # Remove any global variable matches from local (in case pattern overlap) # The global pattern is more specific, so we need to exclude those # that were matched as local but are actually global global_prefixed = {f"global.{v}" for v in global_vars} local_vars = {v for v in local_vars if v not in global_prefixed and not v.startswith("global.")} return local_vars, global_vars def extract_variables_from_test_steps(test_steps: Optional[List[Dict[str, Any]]]) -> Tuple[Set[str], Set[str]]: """ Extract all variables from test steps. Searches through the 'action' and 'expected_result' fields of each test step and extracts all variable references. Args: test_steps: List of test step dictionaries with 'action' and 'expected_result' keys Returns: Tuple of (local_variables, global_variables) as sets of variable names """ all_local: Set[str] = set() all_global: Set[str] = set() if not test_steps: return all_local, all_global for step in test_steps: if not isinstance(step, dict): continue action = step.get('action', '') or '' expected = step.get('expected_result', '') or '' local_action, global_action = extract_variables(str(action)) local_expected, global_expected = extract_variables(str(expected)) all_local.update(local_action) all_local.update(local_expected) all_global.update(global_action) all_global.update(global_expected) return all_local, all_global def substitute_variables( text: str, local_values: Dict[str, Optional[str]], global_values: Optional[Dict[str, Optional[str]]] = None ) -> str: """ Substitute variables in text with their values. Replaces {{variable_name}} with the corresponding value from local_values and {{global.variable_name}} with the corresponding value from global_values. Args: text: Text containing {{variable}} syntax local_values: Dict of local variable name -> value global_values: Dict of global variable name -> value (optional) Returns: Text with variables replaced by their values. If a variable's value is None, it is replaced with an empty string. """ if not text: return text result = text # Substitute global variables first (more specific pattern) if global_values: for name, value in global_values.items(): placeholder = f'{{{{global.{name}}}}}' result = result.replace(placeholder, value if value is not None else '') # Substitute local variables if local_values: for name, value in local_values.items(): placeholder = f'{{{{{name}}}}}' result = result.replace(placeholder, value if value is not None else '') return result def substitute_test_steps( test_steps: Optional[List[Dict[str, Any]]], local_values: Dict[str, Optional[str]], global_values: Optional[Dict[str, Optional[str]]] = None ) -> List[Dict[str, Any]]: """ Substitute variables in all test steps. Creates a new list of test steps with all variable references replaced by their values in the 'action' and 'expected_result' fields. Args: test_steps: Original list of test step dictionaries local_values: Dict of local variable name -> value global_values: Dict of global variable name -> value (optional) Returns: New list of test steps with substituted values. Original test_steps list is not modified. """ if not test_steps: return [] substituted: List[Dict[str, Any]] = [] for step in test_steps: if not isinstance(step, dict): substituted.append(step) continue new_step = step.copy() action = step.get('action', '') if action: new_step['action'] = substitute_variables(str(action), local_values, global_values) expected = step.get('expected_result', '') if expected: new_step['expected_result'] = substitute_variables(str(expected), local_values, global_values) substituted.append(new_step) return substituted def validate_variables_defined( test_steps: Optional[List[Dict[str, Any]]], defined_local_vars: Set[str], defined_global_vars: Optional[Set[str]] = None ) -> Tuple[bool, List[str]]: """ Validate all variables used in test steps are defined. Checks that every variable referenced in the test steps has a corresponding definition. This prevents runtime errors from undefined variables. Args: test_steps: List of test step dictionaries defined_local_vars: Set of defined local variable names defined_global_vars: Set of defined global variable names (optional) Returns: Tuple of (is_valid, list_of_undefined_variables) - is_valid: True if all used variables are defined - list_of_undefined_variables: List of undefined variable references in {{variable}} format """ used_local, used_global = extract_variables_from_test_steps(test_steps) undefined: List[str] = [] # Check local variables for var in used_local: if var not in defined_local_vars: undefined.append(f'{{{{{var}}}}}') # Check global variables (if provided) if defined_global_vars is not None: for var in used_global: if var not in defined_global_vars: undefined.append(f'{{{{global.{var}}}}}') return len(undefined) == 0, undefined def get_data_set_values( data_values: List[Dict[str, Any]], variable_lookup: Dict[int, str] ) -> Dict[str, Optional[str]]: """ Convert data value records to a variable name -> value dictionary. Helper function to transform database records into a format suitable for variable substitution. Args: data_values: List of data value dictionaries with 'variable_id' and 'value' keys variable_lookup: Dict mapping variable_id -> variable_name Returns: Dict of variable_name -> value """ result: Dict[str, Optional[str]] = {} for dv in data_values: variable_id = dv.get('variable_id') if variable_id is not None and variable_id in variable_lookup: var_name = variable_lookup[variable_id] result[var_name] = dv.get('value') return result def mask_sensitive_value(value: Optional[str], is_sensitive: bool = False) -> str: """ Mask a sensitive value for display purposes. Args: value: The value to potentially mask is_sensitive: Whether this value should be masked Returns: The original value if not sensitive, or '********' if sensitive and has a value """ if not is_sensitive or value is None: return value if value is not None else '' return '********' if value else ''