{"id":12955,"library":"chloride-test","title":"Chloride API Compatibility Test Utility","description":"The `chloride-test` package, currently at version 1.2.4, is a specialized JavaScript utility designed to validate that a given module provides the identical cryptographic functions and API signature as the `chloride` library. It achieves this by generating a comprehensive suite of tests based on the `chloridedown` specification, ensuring adherence to the expected interface. This package is primarily used as a development dependency within projects that aim to offer `chloride`-compatible cryptographic primitives, such as wrappers around `libsodium` via `sodium-browserify` or `sodium-native`. Its core function is to maintain interoperability and correctness across different underlying cryptographic implementations. Given its nature as a testing harness for an API standard, its release cadence is typically slow and focused on stability, reflecting minimal feature changes post-initial API definition. It is essential for developers to verify their modules against the `chloride` standard, ensuring consistent behavior across the ecosystem.","status":"maintenance","version":"1.2.4","language":"javascript","source_language":"en","source_url":"git://github.com/dominictarr/chloride-test","tags":["javascript"],"install":[{"cmd":"npm install chloride-test","lang":"bash","label":"npm"},{"cmd":"yarn add chloride-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add chloride-test","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used as the underlying test runner for generated tests.","package":"tape"},{"reason":"Provides conditional logging for debugging test execution.","package":"debug"},{"reason":"Potentially used internally for stream manipulation, common in dominictarr's work.","package":"through2"}],"imports":[{"note":"This package is primarily a CommonJS module and should be imported using `require()`.","wrong":"import chlorideTest from 'chloride-test'","symbol":"chlorideTest","correct":"const chlorideTest = require('chloride-test')"},{"note":"The `chloride-test` package exports a function directly, which takes the module to be tested as an argument.","wrong":"const runTests = require('chloride-test').runTests","symbol":"runTests","correct":"require('chloride-test')(someCryptoModule)"}],"quickstart":{"code":"const test = require('tape');\nconst chlorideTest = require('chloride-test');\n\n// A mock or actual chloride-compatible module, e.g., require('sodium-browserify')\nconst myCryptoModule = {\n  randombytes: (size, cb) => {\n    if (cb) return cb(null, Buffer.alloc(size));\n    return Buffer.alloc(size);\n  },\n  // ... other chloride API methods like `sign`, `verify`, `box`, `open`, etc.\n  // For a real test, 'sodium-browserify' or a similar library would be used here.\n  box: (message, nonce, pk, sk) => Buffer.from('mocked_box_output'),\n  open: (ciphertext, nonce, pk, sk) => Buffer.from('mocked_open_output'),\n  sign: (message, sk) => Buffer.from('mocked_signature'),\n  verify: (signature, message, pk) => true,\n  // ... all other expected chloride functions\n};\n\ntest('myCryptoModule implements chloride API correctly', (t) => {\n  chlorideTest(myCryptoModule, {\n    // Optionally pass in custom options, or let chloride-test generate all possible tests\n    filter: (name) => name.startsWith('randombytes') || name.startsWith('box'),\n    // 'filter' allows running a subset of tests if the full suite is too long or specific\n  });\n\n  // To ensure tape finishes, you might want to call t.end() if chlorideTest doesn't handle it.\n  // In practice, chlorideTest often integrates with tape to manage its own assertions and ending.\n  // For this example, we assume chlorideTest will run its assertions and implicitly manage tape's flow.\n  t.pass('chloride-test suite initiated. Check console for detailed test results.');\n  // For an actual integration, `chloride-test` would drive the `tape` tests itself.\n});","lang":"javascript","description":"This quickstart demonstrates how to use `chloride-test` to validate a module's API against the `chloride` specification. It shows passing a mock `myCryptoModule` (which would typically be `sodium-browserify` or a custom implementation) to the `chlorideTest` function. The example includes `tape` for context, as `chloride-test` typically integrates with it."},"warnings":[{"fix":"Ensure you have a `chloride`-compatible library (e.g., `sodium-browserify`, `sodium-native`, or `chloride` itself) installed and available to pass to `chloride-test`.","message":"The `chloride-test` package is purely a testing utility and does not provide any cryptographic functions itself. It requires you to pass in a separate module that implements the `chloride` API.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the `chloride` and `chloridedown` repositories for any breaking changes to the API. Update your tested cryptographic module to match the expected `chloride` interface.","message":"API changes in `chloride` or `chloridedown` (the test generation source) may cause `chloride-test` to fail or produce incorrect results if the tested module is not updated accordingly. `chloride-test` assumes the `chloride` API defined by its `chloridedown` dependency.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your testing setup is compatible with CommonJS modules. If using ESM, consider a dynamic `import()` or transpilation if absolutely necessary, but it's best used within its intended CJS context.","message":"This package is designed for Node.js environments and uses CommonJS modules. Direct use in browser environments or modern ESM-only Node.js projects without a CJS wrapper or bundler might lead to import errors.","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":"Verify that your `someChlorideFunction` is correctly exported by the module you are passing to `chloride-test`. Check the `chloride` API specification to ensure all required functions are present.","cause":"The module being tested does not export a function that `chloride-test` expects as part of the `chloride` API.","error":"TypeError: module.someChlorideFunction is not a function"},{"fix":"Debug the specific cryptographic function (`someFunction`) within your module. Ensure its implementation adheres strictly to the `chloride` specification, particularly regarding input/output formats, key derivations, and algorithm behavior. This often indicates a bug in your cryptographic wrapper.","cause":"The cryptographic function in the module being tested produced an output that does not match the expected `chloride` behavior for a given input.","error":"Assertion failed: Expected X but got Y for chloride.someFunction"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}