Skip to main content
skill CX Codex

n8n-expression-testing — Claude Code skill: validation

n8n-expression-testing is a Claude Code skill that checks n8n expressions against different data contexts, including missing values, while debugging data transformations.

MIT 127 installs ★ 533 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add proffesor-for-testing/agentic-qe --skill n8n-expression-testing -a claude-code
Open on GitHub

What n8n-expression-testing does

This skill validates the JavaScript inside n8n expressions before execution. It reviews references such as $json, $node, and $items(), then tests expressions against more than one data context, including cases where fields are null or undefined.

Its reference material covers field and array access, node data, dates, string methods, type conversion, and common array operations. The checks also flag risky calls such as eval and Function, while drawing attention to work that may scale poorly with large arrays. A direct property chain can fail when an intermediate object is missing, so that case needs a guard or fallback before the workflow runs.

The skill also maps frequent failures to fixes, including calling string methods on null values, formatting a string as a number, and applying map to a non-array value. A context-based test can return either the expression result or the caught error.

What it helps with

  • validate an n8n expression before execution
  • catch unsafe nested-property access
  • check $json and $node context references
  • spot conversion errors between strings and numbers
  • review array work for large data sets

Example prompts for the agent

  • Validate $json.user?.profile?.email ?? '' for n8n syntax and missing values.
  • Test a transformation of $json.items with several data contexts and confirm that map receives an array.
  • Inspect $node["HTTP"].json.body and report any broken node reference.

How to install n8n-expression-testing

1Skills CLI (Vercel)

npx skills add proffesor-for-testing/agentic-qe --skill n8n-expression-testing -a claude-code

2Manually: put the files in place

~/.claude/skills/n8n-expression-testing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/n8n-expression-testing/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about n8n-expression-testing

How do I install n8n-expression-testing in Claude Code?

Run npx skills add proffesor-for-testing/agentic-qe --skill n8n-expression-testing -a claude-code. The skill file will be at ~/.claude/skills/n8n-expression-testing/SKILL.md.

What does n8n-expression-testing do?

It checks n8n expression syntax, context variables, missing-value handling, and type conversions. It also looks for risky functions and costly array operations.

Which n8n context variables does it cover?

The reference and checks cover $json, $node, $items, $now, $today, $runIndex, and $workflow. Expressions can be tested against supplied context data.

Source text

SKILL.md · MIT
---
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]
trust_tier: 3
validation:
  schema_path: schemas/output.json
  validator_path: scripts/validate-config.json
  eval_path: evals/n8n-expression-testing.yaml
---

# 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 ?? '[email protected]' }}

// 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).

© proffesor-for-testing · MIT · proffesor-for-testing/agentic-qe

Similar skills

All skills for Testing and QA →

From the same set73

The whole set →
qe-quality-assessment qe-quality-assessment reviews code quality through complexity, lint, code smells, and test health. Use it for release scoring, quality gates, and deployment checks. CX Codex +1 129installs qe-defect-intelligence qe-defect-intelligence identifies high-risk code before bugs escape by analyzing change frequency, complexity metrics, and past defect patterns. Flags risky PRs and runs root cause analysis on test failures. CX Codex +1 129installs risk-based-testing risk-based-testing directs QA effort to high-risk areas using a 1-5 probability and impact scale, adjusting test depth dynamically. CX Codex +1 128installs n8n-trigger-testing-strategies n8n-trigger-testing-strategies — a skill for testing how n8n workflows get triggered: webhooks, cron schedules, service events, polling. Useful when a workflow fires at the wrong moment or not at all. CX Codex +1 128installs qe-coverage-analysis qe-coverage-analysis inspects Istanbul, c8, and lcov data to detect untested paths with risk scoring. Useful when prioritizing test efforts or checking PR quality gates. CX Codex +1 127installs test-reporting-analytics test-reporting-analytics generates quality dashboards, executive reports, and failure predictions based on code diffs. Useful when tracking CI/CD trends or preparing release gates. CX Codex +1 126installs qe-iterative-loop qe-iterative-loop — a skill that runs autonomous red-green-refactor cycles: the agent fixes failing tests, achieves coverage targets, and passes quality gates on its own. CX Codex +1 126installs xp-practices xp-practices — a skill for pair programming, continuous integration, TDD, and other extreme programming practices in AI coding. CX Codex +1 125installs

Project sponsors

Companies that keep this analytics open