{"id":13280,"library":"haraka-test-fixtures","title":"Haraka Test Fixtures","description":"The `haraka-test-fixtures` package provides a comprehensive set of mock objects and utilities specifically designed for testing Haraka SMTP server plugins and core components. It enables developers to create isolated test environments by simulating key Haraka abstractions such as `Connection`, `Transaction`, `Plugin`, `Logger`, and `Results` objects without the overhead of running a full Haraka server. This allows for focused unit and integration testing of plugin logic. The current stable version is 1.4.1, released with bug fixes and dependency updates. Releases follow an ad-hoc schedule, primarily driven by maintenance requirements, synchronization with the main Haraka project, and dependency bumps. Its key differentiator lies in its deep integration and direct analogy to Haraka's internal architecture, providing tailor-made testing primitives that generic mocking libraries cannot easily replicate. It helps abstract away the complexities of Haraka's lifecycle for efficient plugin development and testing.","status":"active","version":"1.4.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/haraka/test-fixtures","tags":["javascript"],"install":[{"cmd":"npm install haraka-test-fixtures","lang":"bash","label":"npm"},{"cmd":"yarn add haraka-test-fixtures","lang":"bash","label":"yarn"},{"cmd":"pnpm add haraka-test-fixtures","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The documentation primarily uses CommonJS `require()`. While Node.js 20+ supports ESM, direct default ESM imports might not function as expected for all fixtures or require specific `type: module` configuration.","wrong":"import fixtures from 'haraka-test-fixtures'","symbol":"fixtures","correct":"const fixtures = require('haraka-test-fixtures')"},{"note":"`plugin` is a named export available via the main module object. It should be instantiated to create a plugin fixture.","wrong":"import { plugin } from 'haraka-test-fixtures'","symbol":"plugin","correct":"const { plugin } = require('haraka-test-fixtures');\n// or\nconst fixtures = require('haraka-test-fixtures');\nnew fixtures.plugin('my-plugin')"},{"note":"`connection` is a named export providing static methods, most notably `createConnection()` to generate a connection fixture.","wrong":"import { connection } from 'haraka-test-fixtures'","symbol":"connection","correct":"const { connection } = require('haraka-test-fixtures');\n// or\nconst fixtures = require('haraka-test-fixtures');\nfixtures.connection.createConnection()"}],"quickstart":{"code":"const fixtures = require('haraka-test-fixtures');\n\ndescribe('my-haraka-plugin', () => {\n  let plugin;\n  let connection;\n\n  beforeEach(() => {\n    plugin = new fixtures.plugin('my-plugin');\n    connection = fixtures.connection.createConnection();\n    connection.init_transaction(); // Initialize transaction for a connection\n  });\n\n  it('registers the plugin', () => {\n    plugin.register();\n    // Add assertions based on plugin registration side effects\n    // e.g., expect(plugin.register_hook.calledWith('data', 'onData')).to.be.true;\n  });\n\n  it('handles a connection event', async () => {\n    // Simulate a connection hook being called\n    const next = () => {}; // Mock the 'next' function\n    await plugin.hook_connect(next, connection);\n    // Assert on connection properties or plugin behavior\n    // expect(connection.notes.myValue).to.equal('expected');\n  });\n});","lang":"javascript","description":"Demonstrates how to set up and use `haraka-test-fixtures` to test a Haraka plugin, including creating plugin and connection fixtures and invoking a hook."},"warnings":[{"fix":"Remove all references and usage of `vm_harness` from your test suite. If you had custom logic built around it, you will need to refactor those tests to use alternative fixtures or approaches.","message":"The `vm_harness` fixture was removed in version 1.4.1 because it is no longer used by Haraka. Any tests relying on `vm_harness` will fail.","severity":"breaking","affected_versions":">=1.4.1"},{"fix":"Ensure your development and CI environments are using Node.js version 20 or higher to maintain compatibility and prevent runtime issues.","message":"The package specifies Node.js `>=20` in its engine requirements. Running tests with older Node.js versions might lead to unexpected behavior or runtime errors.","severity":"gotcha","affected_versions":">=1.4.0"},{"fix":"For consistent and documented behavior, use CommonJS `require()` statements (e.g., `const fixtures = require('haraka-test-fixtures')`). If ESM is strictly required, ensure your project's module resolution is correctly configured for CommonJS interop.","message":"While Node.js 20+ supports ES Modules, the documentation and common usage patterns for `haraka-test-fixtures` heavily rely on CommonJS `require()`. Attempting to use ESM `import` statements directly may lead to module resolution issues or require specific `package.json` configurations (`\"type\": \"module\"`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your tests to remove any usage or reference to `vm_harness`. This fixture is no longer part of the package.","cause":"Attempting to instantiate or access the `vm_harness` fixture which was removed in `haraka-test-fixtures` v1.4.1.","error":"TypeError: fixtures.vm_harness is not a constructor"},{"fix":"Ensure that `connection` objects are correctly created using `fixtures.connection.createConnection()` and that necessary initialization methods like `init_transaction()` are called before attempting to use transaction-related features.","cause":"A method is being called on a connection fixture that either hasn't been properly initialized or the method itself doesn't exist for the current state/version of the fixture.","error":"TypeError: this.connection.init_transaction is not a function"},{"fix":"Install the package using npm: `npm install --save-dev haraka-test-fixtures`. Verify the module path if the error persists in a non-standard setup.","cause":"The `haraka-test-fixtures` package has not been installed or is not resolvable from the current project context.","error":"Error: Cannot find module 'haraka-test-fixtures'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}