@agentic-qe/v3 3.0.0-alpha.5 → 3.0.0-alpha.7

package/assets/skills/n8n-expression-testing/SKILL.md

@@ -0,0 +1,434 @@
+---
+name: n8n-expression-testing
+description: "n8n expression syntax validation, context-aware testing, common pitfalls detection, and performance optimization. Use when validating n8n expressions and data transformations."
+category: n8n-testing
+priority: high
+tokenEstimate: 1000
+agents: [n8n-expression-validator]
+implementation_status: production
+optimization_version: 1.0
+last_optimized: 2025-12-15
+dependencies: []
+quick_reference_card: true
+tags: [n8n, expressions, javascript, data-transformation, validation]
+---
+
+# n8n Expression Testing
+
+<default_to_action>
+When testing n8n expressions:
+1. VALIDATE syntax before execution
+2. TEST with multiple context scenarios
+3. CHECK for null/undefined handling
+4. VERIFY type safety
+5. SCAN for security vulnerabilities
+
+**Quick Expression Checklist:**
+- Valid JavaScript syntax
+- Context variables properly referenced ($json, $node)
+- Null-safe access patterns (?., ??)
+- No dangerous functions (eval, Function)
+- Efficient for large data sets
+
+**Common Pitfalls:**
+- Accessing nested properties without null checks
+- Type coercion issues
+- Missing fallback values
+- Inefficient array operations
+</default_to_action>
+
+## Quick Reference Card
+
+### n8n Expression Syntax
+
+| Pattern | Example | Description |
+|---------|---------|-------------|
+| Basic access | `{{ $json.field }}` | Access JSON field |
+| Nested access | `{{ $json.user.email }}` | Access nested property |
+| Array access | `{{ $json.items[0] }}` | Access array element |
+| Node reference | `{{ $node["Name"].json.id }}` | Access other node's data |
+| Method call | `{{ $json.name.toLowerCase() }}` | Call string method |
+| Conditional | `{{ $json.x ? "yes" : "no" }}` | Ternary expression |
+
+### Context Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `$json` | Current item data | `{{ $json.email }}` |
+| `$node["Name"]` | Other node's data | `{{ $node["HTTP"].json.body }}` |
+| `$items()` | Multiple items | `{{ $items("Node", 0, 0).json }}` |
+| `$now` | Current timestamp | `{{ $now.toISO() }}` |
+| `$today` | Today's date | `{{ $today }}` |
+| `$runIndex` | Run iteration | `{{ $runIndex }}` |
+| `$workflow` | Workflow info | `{{ $workflow.name }}` |
+
+---
+
+## Expression Syntax Patterns
+
+### Safe Data Access
+
+```javascript
+// BAD: Can fail if nested objects are null
+{{ $json.user.profile.email }}
+
+// GOOD: Optional chaining with fallback
+{{ $json.user?.profile?.email ?? '' }}
+
+// BAD: Array access without bounds check
+{{ $json.items[0].name }}
+
+// GOOD: Safe array access
+{{ $json.items?.[0]?.name ?? 'No items' }}
+```
+
+### Type Conversions
+
+```javascript
+// String to Number
+{{ parseInt($json.quantity, 10) }}
+{{ parseFloat($json.price) }}
+{{ Number($json.value) }}
+
+// Number to String
+{{ String($json.id) }}
+{{ $json.amount.toString() }}
+{{ $json.count.toFixed(2) }}
+
+// Date handling
+{{ new Date($json.timestamp).toISOString() }}
+{{ DateTime.fromISO($json.date).toFormat('yyyy-MM-dd') }}
+
+// Boolean conversion
+{{ Boolean($json.active) }}
+{{ $json.enabled === 'true' }}
+```
+
+### String Operations
+
+```javascript
+// Case conversion
+{{ $json.name.toLowerCase() }}
+{{ $json.name.toUpperCase() }}
+{{ $json.name.charAt(0).toUpperCase() + $json.name.slice(1) }}
+
+// String manipulation
+{{ $json.text.trim() }}
+{{ $json.text.replace(/\s+/g, ' ') }}
+{{ $json.text.substring(0, 100) }}
+
+// Template strings
+{{ `Hello, ${$json.firstName} ${$json.lastName}!` }}
+{{ `Order #${$json.orderId} - ${$json.status}` }}
+```
+
+### Array Operations
+
+```javascript
+// Mapping
+{{ $json.items.map(item => item.name) }}
+{{ $json.items.map(item => ({ id: item.id, total: item.price * item.qty })) }}
+
+// Filtering
+{{ $json.items.filter(item => item.active) }}
+{{ $json.items.filter(item => item.price > 100) }}
+
+// Reducing
+{{ $json.items.reduce((sum, item) => sum + item.price, 0) }}
+{{ $json.items.reduce((acc, item) => ({ ...acc, [item.id]: item }), {}) }}
+
+// Finding
+{{ $json.items.find(item => item.id === $json.targetId) }}
+{{ $json.items.findIndex(item => item.name === 'target') }}
+
+// Joining
+{{ $json.tags.join(', ') }}
+{{ $json.items.map(i => i.name).join(' | ') }}
+```
+
+---
+
+## Validation Patterns
+
+```typescript
+// Validate expression syntax
+function validateExpressionSyntax(expression: string): ValidationResult {
+  // Remove n8n template markers
+  const code = expression.replace(/\{\{|\}\}/g, '').trim();
+
+  try {
+    // Check if valid JavaScript
+    new Function(`return (${code})`);
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error.message,
+      suggestion: suggestFix(error.message, code)
+    };
+  }
+}
+
+// Validate context variables
+function validateContextVariables(expression: string): string[] {
+  const contextVars = ['$json', '$node', '$items', '$now', '$today', '$runIndex', '$workflow'];
+  const usedVars = [];
+  const invalidVars = [];
+
+  // Find all $ prefixed variables
+  const varPattern = /\$\w+/g;
+  let match;
+
+  while ((match = varPattern.exec(expression)) !== null) {
+    const varName = match[0];
+    if (contextVars.some(cv => varName.startsWith(cv))) {
+      usedVars.push(varName);
+    } else {
+      invalidVars.push(varName);
+    }
+  }
+
+  return { usedVars, invalidVars };
+}
+
+// Test expression with sample data
+function testExpression(expression: string, context: any): TestResult {
+  const code = expression.replace(/\{\{|\}\}/g, '').trim();
+
+  try {
+    // Create function with context
+    const fn = new Function('$json', '$node', '$items', '$now', '$today',
+      `return (${code})`);
+
+    const result = fn(
+      context.$json || {},
+      context.$node || {},
+      context.$items || (() => ({})),
+      context.$now || new Date(),
+      context.$today || new Date()
+    );
+
+    return { success: true, result };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+```
+
+---
+
+## Common Errors and Fixes
+
+### Undefined Property Access
+
+```javascript
+// ERROR: Cannot read property 'email' of undefined
+{{ $json.user.email }}
+
+// FIX 1: Optional chaining
+{{ $json.user?.email }}
+
+// FIX 2: With fallback
+{{ $json.user?.email ?? 'no-email@example.com' }}
+
+// FIX 3: Conditional
+{{ $json.user ? $json.user.email : '' }}
+```
+
+### Type Errors
+
+```javascript
+// ERROR: toLowerCase is not a function (when null)
+{{ $json.name.toLowerCase() }}
+
+// FIX: Null check first
+{{ $json.name?.toLowerCase() ?? '' }}
+
+// ERROR: toFixed is not a function (string instead of number)
+{{ $json.price.toFixed(2) }}
+
+// FIX: Parse as number first
+{{ parseFloat($json.price).toFixed(2) }}
+
+// ERROR: map is not a function (not an array)
+{{ $json.items.map(i => i.name) }}
+
+// FIX: Ensure array
+{{ (Array.isArray($json.items) ? $json.items : []).map(i => i.name) }}
+```
+
+### Node Reference Errors
+
+```javascript
+// ERROR: Node "Previous Node" not found
+{{ $node["Previous Node"].json.data }}
+
+// FIX: Use exact node name (case-sensitive)
+{{ $node["Previous Node1"].json.data }}
+
+// FIX: Add fallback for safety
+{{ $node["Previous Node"]?.json?.data ?? {} }}
+```
+
+---
+
+## Security Patterns
+
+### Dangerous Functions to Avoid
+
+```javascript
+// DANGEROUS: Never use eval
+{{ eval($json.code) }}
+
+// DANGEROUS: Dynamic function creation
+{{ new Function($json.code)() }}
+
+// DANGEROUS: setTimeout with string
+{{ setTimeout($json.code, 1000) }}
+
+// SAFE: Use explicit operations instead
+{{ $json.value * 2 }}
+{{ JSON.parse($json.jsonString) }}
+```
+
+### Input Validation
+
+```javascript
+// Validate email format
+{{ /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test($json.email) ? $json.email : '' }}
+
+// Sanitize for HTML (basic)
+{{ $json.text.replace(/[<>&"']/g, c => ({
+  '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&#39;'
+}[c])) }}
+
+// Limit string length
+{{ $json.input.substring(0, 1000) }}
+
+// Validate number range
+{{ Math.min(Math.max(parseInt($json.value), 0), 100) }}
+```
+
+---
+
+## Performance Optimization
+
+### Efficient Array Operations
+
+```javascript
+// SLOW: Multiple iterations
+{{ $json.items.filter(i => i.active).map(i => i.name).join(', ') }}
+
+// FASTER: Single reduce
+{{ $json.items.reduce((acc, i) => i.active ? (acc ? `${acc}, ${i.name}` : i.name) : acc, '') }}
+
+// SLOW: Nested loops
+{{ $json.items.map(i => $json.categories.find(c => c.id === i.categoryId)) }}
+
+// FASTER: Create lookup map first (in Code node)
+const categoryMap = Object.fromEntries($json.categories.map(c => [c.id, c]));
+return $json.items.map(i => categoryMap[i.categoryId]);
+```
+
+### Avoid in Expressions
+
+```javascript
+// AVOID: Complex logic in expressions
+{{ $json.items.reduce((acc, item) => {
+  const category = $json.categories.find(c => c.id === item.catId);
+  if (category && category.active) {
+    acc.push({ ...item, categoryName: category.name });
+  }
+  return acc;
+}, []) }}
+
+// BETTER: Move to Code node for complex transformations
+```
+
+---
+
+## Testing Patterns
+
+```typescript
+// Expression test suite
+const expressionTests = [
+  {
+    name: 'Basic property access',
+    expression: '{{ $json.name }}',
+    context: { $json: { name: 'John' } },
+    expected: 'John'
+  },
+  {
+    name: 'Nested with optional chaining',
+    expression: '{{ $json.user?.email ?? "default" }}',
+    context: { $json: { user: null } },
+    expected: 'default'
+  },
+  {
+    name: 'Array mapping',
+    expression: '{{ $json.items.map(i => i.id).join(",") }}',
+    context: { $json: { items: [{ id: 1 }, { id: 2 }] } },
+    expected: '1,2'
+  },
+  {
+    name: 'Conditional expression',
+    expression: '{{ $json.score >= 70 ? "Pass" : "Fail" }}',
+    context: { $json: { score: 85 } },
+    expected: 'Pass'
+  },
+  {
+    name: 'Node reference',
+    expression: '{{ $node["Previous"].json.result }}',
+    context: { $node: { Previous: { json: { result: 'success' } } } },
+    expected: 'success'
+  }
+];
+
+// Run tests
+for (const test of expressionTests) {
+  const result = testExpression(test.expression, test.context);
+  console.log(`${test.name}: ${result.result === test.expected ? 'PASS' : 'FAIL'}`);
+}
+```
+
+---
+
+## Agent Coordination
+
+### Memory Namespace
+```
+aqe/n8n/expressions/
+├── validations/*    - Expression validation results
+├── patterns/*       - Discovered expression patterns
+├── errors/*         - Common error catalog
+└── optimizations/*  - Performance suggestions
+```
+
+### Fleet Coordination
+```typescript
+// Coordinate expression validation with workflow testing
+await Task("Validate expressions", {
+  workflowId: "wf-123",
+  validateAll: true,
+  testWithSampleData: true
+}, "n8n-expression-validator");
+```
+
+---
+
+## Related Skills
+- [n8n-workflow-testing-fundamentals](../n8n-workflow-testing-fundamentals/) - Workflow testing
+- [n8n-security-testing](../n8n-security-testing/) - Security validation
+
+---
+
+## Remember
+
+**n8n expressions are JavaScript-like** with special context variables ($json, $node, etc.). Testing requires:
+- Syntax validation
+- Context variable verification
+- Null safety checks
+- Type compatibility
+- Security scanning
+
+**Key patterns:** Use optional chaining (`?.`) and nullish coalescing (`??`) for safety. Move complex logic to Code nodes. Always test with edge cases (null, undefined, empty arrays).