rhizome-node/docs/test-helpers.md

Test Helpers

This document provides documentation for the test helper functions available in the Rhizome Node test suite.

testResolverWithPlugins

An async helper function for testing custom resolvers with plugins and a sequence of deltas. Returns a Promise that resolves to the resolved entity.

Import

import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';

Signature

function testResolverWithPlugins<T>({
  entityId = 'test-entity',
  plugins,
  deltas
}: {
  entityId?: string;
  plugins: Record<string, ResolverPlugin>;
  deltas: Delta[];
}): Promise<ResolvedEntity>;

Parameters

• entityId (optional): The ID of the entity to test (defaults to 'test-entity')
• plugins: An object mapping property names to their respective resolver plugins
• deltas: An array of Delta objects to process

Return Value

A Promise that resolves to the resolved entity with all properties processed by the specified plugins.

Example Usage

import { testResolverWithPlugins, createTestDelta } from '@test-helpers/resolver-test-helper';
import { ConcatenationPlugin } from '@src/views/resolvers/custom-resolvers/builtin-plugins';

describe('MyCustomResolver', () => {
  test('should process deltas correctly', async () => {
    // Define test data
    const entityId = 'entity1';
    
    // Run test with plugins and deltas
    const result = await testResolverWithPlugins({
      entityId,
      plugins: {
        myProperty: new ConcatenationPlugin()
      },
      deltas: [
        createTestDelta('user1', 'host1')
          .setProperty(entityId, 'myProperty', 'value1')
          .buildV1(),
        createTestDelta('user1', 'host1')
          .setProperty(entityId, 'myProperty', 'value2')
          .buildV1()
      ]
    });
    
    // Assert the results
    expect(result).toBeDefined();
    expect(result.properties.myProperty).toBe('value1 value2');
  });
});

createTestDelta

A helper function for creating test deltas with a fluent API.

Example Usage

// Create a simple delta
const delta = createTestDelta('user1', 'host1')
  .withTimestamp(1000)
  .setProperty('entity1', 'tags', 'red', 'color1')
  .buildV1();

// Declare a transaction
const transaction = createTestDelta('user1', 'host1')
  .declareTransaction('tx123', 1)
  .buildV1();

// Create a delta in a transaction
const deltaInTransaction = createTestDelta('user1', 'host1')
  .inTransaction('tx123')
  .setProperty('entity1', 'status', 'active', 'system')
  .buildV1();

How It Works

1. Creates a new Hyperview instance for the test
2. Sets up a CustomResolver with the provided plugins
3. Ingests all provided deltas into the Hyperview instance
4. Retrieves and resolves the view for the specified entity
5. Returns the resolved entity as a Promise

Best Practices

Test Structure

• Use async/await for cleaner test code
• Group related tests in describe blocks
• Use clear, descriptive test names
• Test edge cases like empty states and error conditions

Delta Creation

• Use createTestDelta for consistent delta creation
• Set appropriate timestamps for time-based tests
• Include all necessary properties in test deltas
• Use transactions when testing multi-delta operations

Assertions

• Always check that the result is defined before accessing properties
• Test both happy paths and error conditions
• Consider testing with different plugin configurations
• Verify the complete state of resolved entities, not just individual properties

Performance

• Each test gets a fresh Hyperview instance automatically
• For complex test scenarios, consider using helper functions to create test data
• Keep test data minimal and focused on the specific behavior being tested