@pmoo/testy

Testy

A very simple JS testing framework, for educational purposes. Live at npm at @pmoo/testy.

:arrow_right: Documentación en español aquí

Getting started

npm install --save-dev @pmoo/testy (if you use npm)
yarn add --dev @pmoo/testy (if you use yarn)

Supported Node versions: 8.x or higher

Usage

Writing test suites

A test suite is a file ending _test.js that looks like this:

// my_test.js
const { suite, test, assert } = require('@pmoo/testy');

suite('a boring test suite', () => {
  test('42 is 42, not surprising', () => {
    assert.that(42).isEqualTo(42);
  });
});

A test suite represents a grouping of tests, and it is implemented as a function call to suite passing a name and a zero-argument function, which is the suite body.

A test is implemented as a function call to test(), passing a name and the test body as a zero-argument function.

Inside the test you can call different assertions that are documented in detail later on.

Running Testy

You can run an individual test file using:

$ npx testy my_test.js 

Or, you can run it without arguments to run all the tests (by default it looks on a tests folder located in the project root):

$ npx testy 

You can also add it as the test script for npm/yarn in your package.json:

{
  ...
  "scripts": {
    "test": "npx testy"
  },
  ...
}

And then run the tests using npm test or yarn test.

Configuring Testy

Testy will look for a .testyrc.json configuration file in the project root directory. You can use this configuration as a template (values here are the defaults):

{
  "directory": "./tests",   // directory including your test files
  "filter": ".*_test.js$",  // which convention to use to recognize test files
  "language": "en",         // language of the output messages. "es" and "en" supported for now
  "failFast": false,        // enable/disable fail fast mode (stop as soon as a failed test appears)
  "randomOrder": false      // enable/disable execution of tests in random order
}

These are all the configuration parameters you can set. Feel free to change it according to your needs. When declaring this configuration, every test suite under the tests directory (matching files ending with *test.js) will be executed.

Examples and available assertions

There must be at least one assertion on the test to be valid. These are all the supported assertion types:

• Boolean assertions:
  • assert.that(boolean).isTrue() or assert.isTrue(boolean). It does a strict comparison against true (object === true)
  • assert.that(boolean).isFalse() or assert.isFalse(boolean). It does a strict comparison against false (object === false)
• Equality assertions:
  • assert.that(actual).isEqualTo(expected) or assert.areEqual(actual, expected).
  • assert.that(actual).isNotEqualTo(expected) or assert.areNotEqual(actual, expected)
  • Equality assertions use a deep object comparison (based on Node's assert module) and fail if objects under comparison have circular references.
  • Equality criteria on non-primitive objects can be specified:
    • Passing an extra two-arg comparator function to isEqualTo(expected, criteria) or areEqual(actual, expected, criteria)
    • Passing a method name that actual object understands: isEqualTo(expected, 'myEqMessage') or areEqual(actual, expected, 'myEqMessage')
    • By default, if actual has an equals method it will be used.
    • If we compare undefined with undefined using isEqualTo(), it will make the test fail. For explicit check for undefined, use the isUndefined()/isNotUndefined() assertions documented above.
• Check for undefined presence/absence:
  • assert.that(aValue).isUndefined() or assert.isUndefined(aValue)
  • assert.that(aValue).isNotUndefined() or assert.isNotUndefined(aValue)
• Check for null presence/absence:
  • assert.that(aValue).isNull() or assert.isNull(aValue)
  • assert.that(aValue).isNotNull() or assert.isNotNull(aValue)
• Exception testing:
  • assert.that(() => { ... }).raises(error) or with regex .raises(/part of message/)
  • assert.that(() => { ... }).doesNotRaise(error)
  • assert.that(() => { ... }).doesNotRaiseAnyErrors()
• Numeric assertions:
  • assert.that(aNumber).isNearTo(anotherNumber). There's a second optional argument that indicates the number of digits to be used for precision. Default is 4.
• String assertions:
  • assert.that(string).matches(regexOrString) or assert.isMatching(string, regexOrString)
• Array inclusion:
  • assert.that(collection).includes(object)
  • assert.that(collection).doesNotInclude(object)
  • assert.that(collection).includesExactly(...objects)
• Emptiness
  • assert.that(collection).isEmpty() or assert.isEmpty(collection)
  • assert.that(collection).isNotEmpty() or assert.isNotEmpty(collection)
  • the collection under test can be an Array, a String or a Set

Please take a look at the tests folder, you'll find examples of each possible test you can write. Testy is self-tested.

Running testy globally

If you don't have a NPM project you can install testy globally using npm install -g testy and then run testy <files>

Other features

• Running code before every test: just like many testing frameworks have, there is a way to execute some code before every test in a suite using the before() function. Example:

  const { suite, test, before, assert } = require('@pmoo/testy');
  
  suite('using the before() helper', () => {
    let answer;
  
    before(() => {
      answer = 42;
    });
  
    test('checking the answer', () => {
      assert.that(answer).isEqualTo(42);
    });
  });
  

• Running code after every test: just like many testing frameworks have, there is a way to execute some code after (cleanp) every test in a suite using the after() function. Example:

  const { suite, test, before, after, assert } = require('@pmoo/testy');
  
  suite('using the after() helper', () => {
    let answer;
  
    before(() => {
      answer = 42;
    });
  
    after(() => {
      answer = undefined;
    });
  });
  

• Support for pending tests: if a test has no body, it will be reported as [WIP] and it won't be considered a failure.

• Fail-Fast mode: if enabled, it stops execution in the first test that fails (or has an error). Remaining tests will be marked as skipped.

• Run tests and suites in random order: a good test suite does not depend on a particular order. Enabling this setting is a good way to ensure that.

• Strict check for assertions: if a test does not evaluate any assertion while it is executed, the result is considered an error. Basically, a test with no assertion is considered a "bad" test.

• Explicitly failing or marking a test as pending: there's a possibility of marking a test as failed or pending, for example:

  const { suite, test, fail, pending } = require('@pmoo/testy');
  
  suite('marking tests as failed and pending', () => {
    test('marking as failed', () =>
      fail.with('should not be here'));
    
    test('marking as pending', () =>
      pending.dueTo('did not have time to finish'));
  });
  

  The output includes the messages provided:

  [FAIL] marking as failed
    => should not be here
  [WIP] marking as pending
    => did not have time to finish
  

Why?

Why another testing tool? The main reason is that we want to keep simplicity, something it's hard to see in the main testing tools out there.

• Zero dependencies: right now, this project does not depend on any npm package, making the tool easy to install, and fast: essential to have immediate feedback while doing TDD. This is also good for installing on places where the internet connection is not good and we don't want to download hundreds of libraries.
• Understandable object-oriented code: we want to use this tool for teaching, so eventually we'll look at the code during lessons, and students should be able to see what is going on, and even contributing at it, with no dark magic involved. Also, we try to follow good OO practices.
• Unique set of features: we are not following any specification nor trying to copy behavior from other approaches (like the "xUnit" or "xSpec" way).

"Design Principles Behind Smalltalk" is a source of inspiration for this work. We try to follow the same principles here.

Contributing

Please take a look at the Contributing section.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Facundo Javier Gelatti ⚠️ 💻	Tomer Ben-Rachel ⚠️ 💻	Abraão Duarte 💻	adico 💻 ⚠️	Askar Imran 💻 ⚠️	Nigel Yong 💻	Chelsie Ng 💻
Pablo T ⚠️ 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Changelog

[5.1.0] - 2021-01-13

This release includes a lot of contributions (4 new contributors!), and several refactorings to continue improving the quality of the tool.

Added

• [feature] added after() hook to run code after each test, thank you @adico1!
• [feature] isIncludedIn() and isNotIncludedIn() assertions, thank you @ask-imran for your first contribution!
• [feature] warning message when no tests found, thank you @niyonx for your first contribution!
• [feature] show error when a requested file does not exist, thank you @chelsieng for your first contribution!
• [feature] global error handler

Fixed

• [bug] suite and test names cannot be empty, thank you @ask-imran!
• [bug] includes() and doesNotInclude() matchers only work on Arrays, thank you @trochepablo for your first contribution!
• [bug] color for pending summary was not painted
• [bug] it was possible to mark tests as pending without specifying reason

Refactored

• rename "master" branch to "main"; also, an ADR was added to track the decision that we want a better vocabulary
• parametrizable i18n messages
• write more tests for the i18n module
• throw error objects instead of strings
• speed up tests by not creating error messages on successful assertions
• added some npm scripts for test coverage and dependencies graph
• changes in modularization: extract assertion and test result reporter
• add more tests and increased the current coverage (example 1, example 2)
• formatter object decoupled from console ui (ADR 0004 added here)
• avoid test doubles at all (ADR 0005 added here), removed test runner double

... and more minor cleanups.