nx-xetest

TypeScript-first, integration-friendly test runner for the Xronox ecosystem.

Overview

xetest is a test runner designed for integration testing in the Xronox ecosystem. It:

• Runs tests using a Jest/Vitest-like DSL (describe, test, expect, hooks)
• Uses real databases via @xronoces/xronox as the data tier
• Uses real APIs (HTTP calls) when tests say they need them
• Standardizes logging via logs-gateway (with Shadow Logging)
• Centralizes all config via nx-config2

Installation

npm install --save-dev nx-xetest

Quick Start

Create a test file:

// src/my.test.ts
import { describe, test, expect, useTestContext } from 'nx-xetest';

describe('my feature', () => {
  test('does something', () => {
    expect(1 + 1).toBe(2);
  });
});

Run tests:

npx xetest

Configuration

Create a .env.test file:

# Database (xronox/nxMongo)
XETEST_DB_ENABLED=true
XETEST_DB_ENGINE=nxMongo
XETEST_DB_NAME=xetest

# Logging
XETEST_LOG_LEVEL=debug
XETEST_LOG_FORMAT=text
XETEST_LOG_TO_CONSOLE=true

# Shadow logs for CI
XETEST_SHADOW_ENABLED=true
XETEST_SHADOW_PER_TEST=true
XETEST_SHADOW_DIR=./test-artifacts/shadow

# API
XETEST_API_ENABLED=true
XETEST_API_BASE_URL=http://localhost:3000
XETEST_API_TIMEOUT=10s

Usage Examples

Pure Unit Tests

import { test, expect } from 'nx-xetest';

test('pure function', () => {
  const input = { a: 1, b: 2 };
  const result = myFn(input);
  expect(result).toEqual({ sum: 3 });
});

Database Tests

import { describe, test, expect, useTestContext } from 'nx-xetest';

describe('user database', () => {
  test('writes to DB', async () => {
    const ctx = useTestContext();
    await ctx.withDb(async (xronox) => {
      await xronox.write({
        dataType: 'metadata',
        sourceType: 'database',
        subSourceType: 'mongo',
        source: 'users',
        document: { email: '[email protected]' },
      });

      const users = await xronox.read({
        dataType: 'metadata',
        sourceType: 'database',
        subSourceType: 'mongo',
        source: 'users',
        query: { email: { $eq: '[email protected]' } },
      });

      expect(users.length).toBe(1);
    });
  }, { tags: ['db'] });
});

API Tests

import { describe, test, expect, useTestContext } from 'nx-xetest';

describe('user API', () => {
  test('creates user via API', async () => {
    const { httpClient, logger, runId } = useTestContext();

    const res = await httpClient!.post('/api/v1/users', {
      email: '[email protected]',
      password: 'test123',
    });

    expect(res.status).toBe(201);
  }, { tags: ['api'] });
});

Integration Tests (DB + API)

import { describe, test, expect, useTestContext } from 'nx-xetest';

describe('user profile API', () => {
  test('creates user in DB via API', async () => {
    const { httpClient, xronox, logger } = useTestContext();

    const res = await httpClient!.post('/api/v1/users', {
      email: '[email protected]',
    });

    expect(res.status).toBe(201);

    const users = await xronox!.read({
      dataType: 'metadata',
      sourceType: 'database',
      subSourceType: 'mongo',
      source: 'users',
      query: { email: { $eq: '[email protected]' } },
    });

    expect(users.length).toBe(1);
  }, { tags: ['db', 'api'] });
});

CLI

# Run all tests (default patterns)
npx xetest

# Run specific patterns
npx xetest "src/**/*.test.ts"

# With env config overrides
XETEST_DB_NAME=xetest \
XETEST_LOG_LEVEL=debug \
npx xetest

Test Tags

Tests can be tagged to indicate their requirements:

• 'db' - Requires database (xronox)
• 'api' - Requires API (httpClient)
• 'slow' - Slow-running test

If a test requires a resource that's not available, it will be skipped with a clear reason.

Configuration Options

See docs/specs.md for full configuration documentation.

License

ISC