ElasticDash Test Runner

Common errors

• Error: Must be run with Node.js version 20.0.0 or higher.

  cause Attempting to run the test runner with an incompatible Node.js version.
  fix Upgrade your Node.js environment to version 20.0.0 or later. Use `nvm install 20 && nvm use 20` or similar.

• TypeError: test is not a function

  cause The `test` function (or `describe`, `configure`) was imported incorrectly, often via a default import or a CommonJS `require` call in an ESM context.
  fix Ensure you are using named ES module imports: `import { test, describe, configure } from 'elasticdash-test';`.

• Error: ElasticDash API Key not configured. Please set 'apiKey' in configure() or ELASTICDASH_API_KEY environment variable.

  cause The `configure` function was called without an `apiKey` or the `ELASTICDASH_API_KEY` environment variable is missing/empty.
  fix Provide a valid API key through `configure({ apiKey: 'your-key' })` or by setting the `ELASTICDASH_API_KEY` environment variable before running tests.

• SyntaxError: Cannot use import statement outside a module

  cause An ES module file (e.g., your test file) is being run in a CommonJS context without proper configuration.
  fix Add `"type": "module"` to your `package.json` or rename your test files to have a `.mjs` extension. Ensure your test runner command respects ESM.

Warnings

• breaking The package is in early `0.x` development (current version 0.1.19). Frequent breaking changes to the API, configuration, and underlying AI models are highly probable. Users should pin exact versions and review changelogs carefully.
  Fix: Always pin exact versions in `package.json` (e.g., `"elasticdash-test": "0.1.19"`) and review release notes before upgrading to new `0.x` versions.
• breaking This package requires Node.js version 20.0.0 or higher. Running with older Node.js versions will result in errors due to unsupported syntax or APIs.
  Fix: Upgrade your Node.js environment to version 20.0.0 or later. Use a version manager like `nvm` (`nvm install 20 && nvm use 20`).
• gotcha Configuration for ElasticDash API keys and endpoints is critical for the AI-native features to function. Improper or missing configuration will lead to authentication errors or non-functional AI capabilities.
  Fix: Ensure `configure({ apiKey: process.env.ELASTICDASH_API_KEY, ... })` is called at the entry point of your test setup, with valid credentials preferably loaded from secure environment variables.
• gotcha As an ESM-only package, CommonJS `require()` statements are not supported for importing `elasticdash-test` modules. Attempting to use `require` will result in runtime errors.
  Fix: Always use ES module `import` syntax (e.g., `import { test } from 'elasticdash-test';`). Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` file extension).

Install

• npm install elasticdash-test npm
• yarn add elasticdash-test yarn
• pnpm add elasticdash-test pnpm

Imports

• test
  wrong:

  const { test } = require('elasticdash-test');

  correct:

  import { test } from 'elasticdash-test';

  Primary entry point for defining individual test cases. ESM-only usage is enforced by Node.js engine requirement.
• describe
  wrong:

  import describe from 'elasticdash-test'; // 'describe' is a named export

  correct:

  import { describe } from 'elasticdash-test';

  Used for grouping related test cases. ESM-only due to Node.js engine requirement. Ensure it's a named import.
• configure
  wrong:

  const configure = require('elasticdash-test').configure;

  correct:

  import { configure } from 'elasticdash-test';

  Used for global configuration, such as setting API keys or ElasticDash connection details. Essential for AI-native features.

Quickstart

Demonstrates defining a test suite for a user management workflow, including global configuration and basic assertions against simulated ElasticDash API interactions. It highlights the use of `test`, `describe`, and `configure`.

import { test, describe, expect, configure } from 'elasticdash-test';

// Configure the test runner with your ElasticDash API key
// It's recommended to load this from environment variables.
configure({
  apiKey: process.env.ELASTICDASH_API_KEY ?? '',
  endpoint: process.env.ELASTICDASH_API_ENDPOINT ?? 'https://api.elasticdash.com'
});

describe('User Management Workflow', () => {
  test('should create a new user successfully', async () => {
    // Simulate interaction with an ElasticDash workflow or API
    // In a real scenario, this would involve calling the ElasticDash API client
    const newUser = { id: 'user-123', name: 'John Doe', email: 'john.doe@example.com' };
    const response = await simulateCreateUser(newUser);

    expect(response.status).toBe(200);
    expect(response.body.message).toBe('User created');
    expect(response.body.user.name).toBe('John Doe');
  });

  test('should retrieve an existing user', async () => {
    const userId = 'user-456';
    const user = await simulateGetUser(userId);

    expect(user).not.toBeNull();
    expect(user.id).toBe(userId);
    expect(user.name).toBe('Jane Doe');
  });
});

async function simulateCreateUser(user: any) {
  // Placeholder for actual ElasticDash API call
  return Promise.resolve({
    status: 200,
    body: { message: 'User created', user }
  });
}

async function simulateGetUser(id: string) {
  // Placeholder for actual ElasticDash API call
  if (id === 'user-456') {
    return Promise.resolve({ id: 'user-456', name: 'Jane Doe', email: 'jane.doe@example.com' });
  }
  return Promise.resolve(null);
}

// To run:
// 1. Save as 'user.test.ts'
// 2. Set ELASTICDASH_API_KEY and ELASTICDASH_API_ENDPOINT environment variables
// 3. Run: npx elasticdash-test user.test.ts