log-dd

By taking TDD one step further, and specifying what the log output should look like before writing the code we can expect that the logs will give maintainers clear and useful logs.

Getting Started

Prerequisites

• NPM 6
• Typescript

Installing in your application

$ npm i -D log-dd

In each test file, import logCapture and chaiLog. logCapture.start/reset/stop() should be called before and after tests.

import chai, { expect } from 'chai';
import { logCapture, chaiLog } from 'log-dd';

chai.use(chaiLog);

// These lines can be omitted if you provide .mocharc.json and do not run `mocha --watch`
before(() => logCapture.start());
afterEach(() => logCapture.reset());
after(() => logCapture.stop());

describe('your feature', () => {
  it('does somthing', () => {
    console.info('Hello World!');
    expect(logCapture).that.console.info.includes('Hello World!');
  });
});

Alternatively, Mocha supports root hook plugins.

.mocharc.json

{ "require": ["log-dd/dist/mocha-log-hooks"] }

API

logCapture

• start() monkey-patches the following methods of console, disabling output and saving the records internally
  • trace()
  • debug()
  • info()
  • log() - retrieves all log records, prefixed with the level of each record
  • warn()
  • error()
• stop() resets the patched methods to their original implementation.
• reset() clears the saved records
• get([trace|debug|info|log|warn|error]) returns an array of formatted strings logged at or above the specified level. If the level is 'log' or not specified all log records will be returned, prefixed with the level.
• log() prints all of the saved records using the original console methods.

Chai Plugin

chaiLog adds a console property to the Chai assertion API with methods to access:

Each of these methods can be used with a string or array of strings to compare against:

console.debug('will not be included for "info"');
console.info('Hello World!');
console.error('expected error');
expect(logCapture).to.console.info(
  `Hello World!
expected error`
);

The methods can also be used without a parameter list and an array assertion will be returned:

expect(logCapture).that.console.info.includes('Hello World!');

The logCapture is actually redundant. A function may be provided in its place:

expect(() => console.info('Hello World!')).to.console.info('Hello World!');

Jest Matcher

jestLog provides the following Jest Matchers:

• console()
• console_trace()
• console_debug()
• console_info()
• console_log()
• console_warn()
• console_error()

The matchers accept an optional expected parameter which can be a multi-line string or an array of strings. If no expected parameter is provided to the methods then the log records will be compared against a snapshot using jest-snapshot.

jest.config.js

/** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
// eslint-disable-next-line no-undef
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testMatch: ['**/*.spec.ts'],
  setupFilesAfterEnv: ['./test/setup-jest.ts']
};

test/setup-jest.ts

import jestLog from 'log-dd';
expect.extend(jestLog);

test.spec.ts

import { jestLog } from 'log-dd';
import logCapture from '../log-capture';

describe('feature', () => {
  beforeAll(() => logCapture.start());
  afterEach(() => logCapture.reset());
  afterAll(() => logCapture.stop());

  test('match snapshot', () => {
    console.info('Hello World!');
    expect(logCapture).console_info();
  });

  test('match string', () => {
    console.info('Hello World!');
    expect(logCapture).console_info('Hello World!');
  });
});

Testing

Lint

$ npm run lint
$ npm run format

or, do it all together as the pre-commit hook does:

$ npm run format:lint:fix

Unit Tests

$ npm test
or
$ npm run test:tdd

Coverage Report

$ npm run coverage

Technology

• Typescript - Typescript transpiler
• Mocha - Unit testing framework
• Chai - Unit testing assertions
• Istanbul - Code coverage
• ChanceJS - Values random generator for unit testing

Best Practices and Coding Patterns

• Clean Code

Contributors

• Nick Albion

Project scaffold generated by yo palo.