ospec: Noiseless Testing Framework

Common errors

• TypeError: o is not a function

  cause The 'o' function was not correctly imported or required, or you might be trying to access a property on an undefined 'o'.
  fix Ensure you have `const o = require('ospec')` for CommonJS or `import o from 'ospec'` for ESM at the top of your test file.

• Error: Timeout awaiting async test

  cause An asynchronous test or hook function did not call the `done()` callback or return a Promise within the default timeout period.
  fix For callback-style async tests, ensure `done()` is called when the async operation completes. For Promise-based tests, ensure the test function returns the Promise. You may also need to increase the timeout for long-running async operations.

• Error: assertion failed

  cause An assertion condition was not met (e.g., `o(1).equals(2)`).
  fix Review the values being asserted and the expected outcomes. Ensure your test logic correctly produces the state you're asserting against. Use `deepEquals` for object comparison instead of `equals`.

Warnings

• breaking The ospec API surface is currently undergoing changes. Both legacy and updated APIs are present to ease transition, but users relying on older patterns should anticipate potential breaking changes in future major releases once legacy code is removed.
  Fix: Review your test suites periodically against the latest documentation and migration guides for updated API usage. Adapt to new patterns to ensure forward compatibility.
• gotcha Asynchronous tests in ospec require calling the `done()` callback or returning a Promise to signal completion. Failing to do so will cause the test to exit prematurely or time out.
  Fix: For callback-style async tests, ensure the `done` argument is accepted and called upon test completion. For Promise-based tests, return the Promise from the test function.
• gotcha When providing a description for an assertion, ospec uses a function call `o(...).equals(...)('description')` or template literal syntax `o(...).equals(...) `description``. Using a comma `o(...).equals(..., 'description')` is incorrect and will be treated as an additional argument to the assertion method.
  Fix: Use either `o(val).equals(expected)('Your assertion description')` or `o(val).equals(expected) `Your assertion description`` for adding descriptions to assertions.

Install

• npm install ospec npm
• yarn add ospec yarn
• pnpm add ospec pnpm

Imports

• o
  wrong:

  const o = require('ospec').o

  correct:

  import o from 'ospec'

  ospec exports the main 'o' function as a default export in both CommonJS and ESM. Avoid destructuring 'o' from the require statement.
• o
  wrong:

  import o from 'ospec'

  correct:

  const o = require('ospec')

  For CommonJS environments, 'o' is the direct module.exports. Using ESM import syntax in a CJS context will result in syntax errors.
• o.spec
  wrong:

  import { spec } from 'ospec'

  correct:

  import o from 'ospec'; o.spec('group', () => { /* ... */ })

  'o.spec' is a method on the default exported 'o' function, not a named export itself. Import 'o' first, then access 'spec' as a property.

Quickstart

Demonstrates basic test definition, grouping, nested groups, assertions, spy usage, and asynchronous testing with ospec.

import o from 'ospec';

// Basic test and assertions
o.spec("math operations", function() {
    o("addition works", function() {
        o(1 + 1).equals(2)("basic addition assertion");
        o(2 + 2).equals(4);
    });

    o("subtraction works", function() {
        o(1 - 1).notEquals(2)("basic subtraction assertion");
    });

    // Nested test groups
    o.spec("arithmetics details", function() {
        o("multiplication also works", function() {
            o(2 * 3).equals(6);
        });
    });
});

// Example with o.spy for function call tracking
function executeCallback(cb, arg) {
    cb(arg);
}

o.spec("executeCallback()", function() {
    o("calls the provided callback with the argument", function() {
        var spy = o.spy();
        executeCallback(spy, "test-argument");

        o(spy.callCount).equals(1)("spy should be called once");
        o(spy.args[0]).equals("test-argument")("first call argument should match");
        o(spy.calls[0].args).deepEquals(["test-argument"])("full call arguments should deep equal");
    });
});

// To run the tests, typically you would run this file via the `ospec` CLI or call o.run()
// Assuming a simple setup where tests are executed on file load, 
// or for explicit execution, the 'ospec' runner needs to be invoked. 
// For demonstration, we simulate running all defined tests.
// In a real CLI setup, this explicit `o.run()` might not be needed.
// However, if running directly in Node, it might be. Let's omit for general quickstart.
// A typical setup would involve `npx ospec my-tests.js`

// Example of an async test
o.spec("async operations", function() {
    o("handles promises correctly", function(done) {
        Promise.resolve(5).then(result => {
            o(result).equals(5);
            done(); // Important for async tests to signal completion
        });
    });
});