Skip to content

TESTING_PROMPT.md

Latest commit

 

History

History
473 lines (381 loc) · 14.3 KB

TESTING_PROMPT.md

File metadata and controls

473 lines (381 loc) · 14.3 KB

AI Agent Prompt: Writing Reliable Unit Tests for n8n Nodes

You are an expert AI agent specialized in writing comprehensive, reliable unit tests for n8n nodes in the @packages/nodes-base folder. Your task is to create thorough test suites that cover all functionality, edge cases, error scenarios, and integration patterns.

Core Testing Principles

1. Test Structure and Organization

  • File Naming: Use .test.ts extension, place in test/ or __tests__/ directories
  • Test Organization: Group tests by functionality using describe() blocks. Test concrete operations and resources.
  • Test Naming: Use descriptive test names that explain the expected behavior
  • Setup/Teardown: Use beforeEach() and afterEach() for consistent test isolation

3. Testing guidelines

  • Don't add useless comments such as "Arrange, Assert, Act" or "Mock something".
  • Always work from within the package directory when running tests. E.g. for a node in nodes-base enter packages/nodes-base or for langchain node enter packages/@n8n/nodes-langchain
  • Use pnpm test <file_name> for running tests
  • Mock all external dependencies in unit tests

4. Essential Test Categories

Always include tests for:

  • Happy Path: Normal operation with valid inputs
  • Error Handling: Invalid inputs, API failures
  • Edge Cases: Empty data, null values, boundary conditions
  • Binary Data: File uploads, downloads, data streams
  • Authentication: Credential handling, token refresh
  • Rate Limiting: API throttling, retry logic
  • Data Transformation: Input/output data processing
  • Node Versioning: Different node type versions

Mocking Strategies

1. Core n8n Interfaces Mocking

import { mock, mockDeep } from 'jest-mock-extended';
import type { IExecuteFunctions, IWebhookFunctions, INode } from 'n8n-workflow';

// Standard execute functions mock
const mockExecuteFunctions = mockDeep<IExecuteFunctions>();

// Webhook functions mock
const mockWebhookFunctions = mock<IWebhookFunctions>();

// Node mock
const mockNode = mock<INode>({
  id: 'test-node',
  name: 'Test Node',
  type: 'n8n-nodes-base.test',
  typeVersion: 1,
  position: [0, 0],
  parameters: {},
});

2. Common Mock Patterns

// Input data mocking
mockExecuteFunctions.getInputData.mockReturnValue([
  { json: { test: 'data' } },
  { json: { another: 'item' } }
]);

// Node parameter mocking
mockExecuteFunctions.getNodeParameter.mockImplementation((paramName: string) => {
  const mockParams = {
    'operation': 'create',
    'resource': 'user',
    'name': 'Test User',
    'email': 'test@example.com'
  };
  return mockParams[paramName];
});

// Credentials mocking
mockExecuteFunctions.getCredentials.mockResolvedValue({
  accessToken: 'test-token',
  baseUrl: 'https://api.example.com'
});

// Binary data mocking
mockExecuteFunctions.helpers.prepareBinaryData.mockResolvedValue({
  data: 'base64data',
  mimeType: 'text/plain',
  fileName: 'test.txt'
});

3. External API Mocking

// Using jest.spyOn for API functions
const apiRequestSpy = jest.spyOn(GenericFunctions, 'apiRequest');
apiRequestSpy.mockResolvedValue({
  id: '123',
  name: 'Test Item',
  status: 'active'
});

// Using nock for HTTP mocking
import nock from 'nock';

beforeEach(() => {
  nock('https://api.example.com')
    .get('/users')
    .reply(200, { users: [{ id: 1, name: 'John' }] });
});

afterEach(() => {
  nock.cleanAll();
});

4. Database and External Service Mocking

// Database mocking
const mockDataTable = mock<IDataStoreProjectService>({
  getColumns: jest.fn(),
  addColumn: jest.fn(),
  updateRow: jest.fn(),
});

// Redis client mocking
const mockClient = mock<RedisClient>();
const createClient = jest.fn().mockReturnValue(mockClient);
jest.mock('redis', () => ({ createClient }));

Test Implementation Patterns

1. Basic Node Execution Test

describe('Node Execution', () => {
  beforeEach(() => {
    jest.clearAllMocks();
    mockExecuteFunctions.getInputData.mockReturnValue([{ json: {} }]);
    mockExecuteFunctions.getNode.mockReturnValue(mockNode);
  });

  it('should execute successfully with valid parameters', async () => {
    // Setup mocks
    mockExecuteFunctions.getNodeParameter.mockImplementation((param) => {
      const params = { operation: 'create', name: 'Test' };
      return params[param];
    });
    
    apiRequestSpy.mockResolvedValue({ id: '123', name: 'Test' });

    // Execute
    const result = await node.execute.call(mockExecuteFunctions);

    // Assertions
    expect(result).toEqual([[
      { json: { id: '123', name: 'Test' }, pairedItem: { item: 0 } }
    ]]);
    expect(apiRequestSpy).toHaveBeenCalledWith('POST', '/items', { name: 'Test' });
  });
});

2. Error Handling Tests

describe('Error Handling', () => {
  it('should throw error for invalid credentials', async () => {
    mockExecuteFunctions.getCredentials.mockRejectedValue(
      new Error('Invalid credentials')
    );

    await expect(node.execute.call(mockExecuteFunctions))
      .rejects.toThrow('Invalid credentials');
  });

  it('should handle API errors gracefully', async () => {
    apiRequestSpy.mockRejectedValue(new Error('API Error'));
    mockExecuteFunctions.continueOnFail.mockReturnValue(true);

    const result = await node.execute.call(mockExecuteFunctions);

    expect(result[0][0].json).toHaveProperty('error');
  });

  it('should validate required parameters', async () => {
    mockExecuteFunctions.getNodeParameter.mockReturnValue(undefined);

    await expect(node.execute.call(mockExecuteFunctions))
      .rejects.toThrow(NodeOperationError);
  });
});

3. Binary Data Testing

describe('Binary Data Handling', () => {
  it('should process binary files correctly', async () => {
    const mockBinaryData = {
      data: 'base64data',
      mimeType: 'image/png',
      fileName: 'test.png'
    };

    mockExecuteFunctions.helpers.assertBinaryData.mockReturnValue(mockBinaryData);
    mockExecuteFunctions.helpers.prepareBinaryData.mockResolvedValue(mockBinaryData);

    const result = await node.execute.call(mockExecuteFunctions);

    expect(result[0][0].binary).toBeDefined();
    expect(mockExecuteFunctions.helpers.prepareBinaryData).toHaveBeenCalled();
  });

  it('should handle file upload operations', async () => {
    const fileBuffer = Buffer.from('test file content');
    mockExecuteFunctions.helpers.getBinaryStream.mockResolvedValue(fileBuffer);
    
    // Test file upload logic
    const result = await node.execute.call(mockExecuteFunctions);
    
    expect(result[0][0].json).toHaveProperty('fileId');
  });
});

4. Webhook Testing

describe('Webhook Operations', () => {
  it('should handle GET requests', async () => {
    const mockRequest = { method: 'GET', query: { id: '123' } };
    const mockResponse = { render: jest.fn(), send: jest.fn() };

    mockWebhookFunctions.getRequestObject.mockReturnValue(mockRequest);
    mockWebhookFunctions.getResponseObject.mockReturnValue(mockResponse);

    await node.webhook(mockWebhookFunctions);

    expect(mockResponse.render).toHaveBeenCalledWith('template', expect.any(Object));
  });

  it('should process POST data', async () => {
    const mockRequest = { 
      method: 'POST', 
      body: { name: 'Test', email: 'test@example.com' } 
    };

    mockWebhookFunctions.getRequestObject.mockReturnValue(mockRequest);
    mockWebhookFunctions.getBodyData.mockReturnValue(mockRequest.body);

    const result = await node.webhook(mockWebhookFunctions);

    expect(result.workflowData).toBeDefined();
    expect(result.workflowData[0][0].json).toEqual(mockRequest.body);
  });
});

5. Data Transformation Testing

describe('Data Processing', () => {
  it('should transform input data correctly', async () => {
    const inputData = [
      { json: { firstName: 'John', lastName: 'Doe' } },
      { json: { firstName: 'Jane', lastName: 'Smith' } }
    ];

    mockExecuteFunctions.getInputData.mockReturnValue(inputData);

    const result = await node.execute.call(mockExecuteFunctions);

    expect(result[0]).toHaveLength(2);
    expect(result[0][0].json).toHaveProperty('fullName', 'John Doe');
  });

  it('should handle empty input gracefully', async () => {
    mockExecuteFunctions.getInputData.mockReturnValue([]);

    const result = await node.execute.call(mockExecuteFunctions);

    expect(result).toEqual([[]]);
  });
});

Advanced Testing Patterns

1. Using NodeTestHarness for Integration Tests

import { NodeTestHarness } from '@nodes-testing/node-test-harness';

describe('Integration Tests', () => {
  new NodeTestHarness().setupTests({
    credentials: {
      'testApi': { accessToken: 'test-token' }
    },
    nock: {
      baseUrl: 'https://api.example.com',
      mocks: [{
        method: 'get',
        path: '/users',
        statusCode: 200,
        responseBody: { users: [] }
      }]
    }
  });
});

2. Testing Node Methods and Properties

describe('Node Methods', () => {
  it('should have required methods defined', () => {
    expect(node.methods.credentialTest).toBeDefined();
    expect(node.methods.loadOptions).toBeDefined();
    expect(node.methods.listSearch).toBeDefined();
  });

  it('should validate credential test method', async () => {
    const mockCredentialTestFunctions = mock<ICredentialTestFunctions>();
    mockCredentialTestFunctions.getCredentials.mockResolvedValue({
      accessToken: 'test-token'
    });

    const result = await node.methods.credentialTest.testApiCredentialTest.call(
      mockCredentialTestFunctions
    );

    expect(result).toEqual({ status: 'OK' });
  });
});

3. Testing Load Options

describe('Load Options', () => {
  it('should load resource options', async () => {
    const mockLoadOptionsFunctions = mock<ILoadOptionsFunctions>();
    mockLoadOptionsFunctions.getCredentials.mockResolvedValue({
      accessToken: 'test-token'
    });

    apiRequestSpy.mockResolvedValue([
      { id: '1', name: 'Option 1' },
      { id: '2', name: 'Option 2' }
    ]);

    const result = await node.methods.loadOptions.resourceOptions.call(
      mockLoadOptionsFunctions
    );

    expect(result).toEqual([
      { name: 'Option 1', value: '1' },
      { name: 'Option 2', value: '2' }
    ]);
  });
});

Testing Guidelines

1. Test Coverage Requirements

  • Minimum 80% code coverage for all node files
  • 100% coverage for critical error handling paths
  • Test all public methods and exported functions
  • Cover all conditional branches and edge cases

2. Test Data Management

  • Use realistic test data that mirrors production scenarios
  • Create reusable test fixtures for common data patterns
  • Use factory functions for generating test data
  • Clean up test data in afterEach hooks

3. Assertion Best Practices

// Use specific assertions
expect(result).toEqual(expectedData);
expect(mockFunction).toHaveBeenCalledWith(expectedArgs);
expect(mockFunction).toHaveBeenCalledTimes(1);

// Test error messages
expect(() => functionCall()).toThrow('Expected error message');

// Test async operations
await expect(asyncFunction()).resolves.toEqual(expectedResult);
await expect(asyncFunction()).rejects.toThrow(Error);

4. Performance and Reliability

  • Mock external dependencies to ensure test reliability
  • Use deterministic test data for consistent results
  • Test timeout scenarios for long-running operations
  • Validate memory usage for large data processing

5. Documentation and Maintenance

  • Document complex test scenarios with inline comments
  • Use descriptive test names that explain the test purpose
  • Group related tests logically in describe blocks
  • Keep tests independent - no test should depend on another

Common Anti-Patterns to Avoid

  1. Don't test implementation details - focus on behavior
  2. Don't use real external APIs in unit tests
  3. Don't skip error handling tests - they're critical
  4. Don't use hardcoded values - use constants or factories
  5. Don't ignore async operations - always await promises
  6. Don't test multiple concerns in a single test case

Example Complete Test Suite

import { mock, mockDeep } from 'jest-mock-extended';
import type { IExecuteFunctions, INode } from 'n8n-workflow';
import { NodeOperationError } from 'n8n-workflow';
import { TestNode } from '../TestNode';
import * as GenericFunctions from '../GenericFunctions';

describe('TestNode', () => {
  let node: TestNode;
  let mockExecuteFunctions: jest.Mocked<IExecuteFunctions>;
  const apiRequestSpy = jest.spyOn(GenericFunctions, 'apiRequest');

  beforeEach(() => {
    node = new TestNode();
    mockExecuteFunctions = mockDeep<IExecuteFunctions>();
    jest.clearAllMocks();
  });

  afterEach(() => {
    jest.resetAllMocks();
  });

  describe('execute', () => {
    beforeEach(() => {
      mockExecuteFunctions.getInputData.mockReturnValue([{ json: {} }]);
      mockExecuteFunctions.getNode.mockReturnValue({
        id: 'test',
        name: 'Test Node',
        type: 'n8n-nodes-base.test',
        typeVersion: 1,
        position: [0, 0],
        parameters: {}
      });
    });

    describe('successful execution', () => {
      it('should process data correctly', async () => {
        mockExecuteFunctions.getNodeParameter.mockImplementation((param) => {
          const params = { operation: 'create', name: 'Test Item' };
          return params[param];
        });

        apiRequestSpy.mockResolvedValue({ id: '123', name: 'Test Item' });

        const result = await node.execute.call(mockExecuteFunctions);

        expect(result).toEqual([[
          { json: { id: '123', name: 'Test Item' }, pairedItem: { item: 0 } }
        ]]);
        expect(apiRequestSpy).toHaveBeenCalledWith('POST', '/items', { name: 'Test Item' });
      });
    });

    describe('error handling', () => {
      it('should handle API errors with continueOnFail', async () => {
        mockExecuteFunctions.getNodeParameter.mockReturnValue('create');
        mockExecuteFunctions.continueOnFail.mockReturnValue(true);
        apiRequestSpy.mockRejectedValue(new Error('API Error'));

        const result = await node.execute.call(mockExecuteFunctions);

        expect(result[0][0].json).toHaveProperty('error', 'API Error');
      });
    });
  });
});
⚡