`@hirez_io/jest-given` 📃👌

A jest addon that helps you clean up your microtests by breaking them into a "Given / When / Then" structure.

Installation

yarn add -D @hirez_io/jest-given

npm install -D @hirez_io/jest-given

Configuring Jest

Add the following line to your jest config:

"setupFilesAfterEnv": ["node_modules/@hirez_io/jest-given/dist/jest-given.js"]

⚠ ATTENTION: If you have configured rootDir -

Make sure you have the right path to node_modules.

For example:

"rootDir": "src",
"setupFilesAfterEnv": ["../node_modules/@hirez_io/jest-given/dist/jest-given.js"]

Using TypeScript?

You should add @hirez_io/jest-given to your types property in your tsconfig.json (or tsconfig.spec.json) like this:

// tsconfig.json or tsconfig.spec.json

{
  ...
  "types": [
      "jest",
      "@hirez_io/jest-given", // <-- ADD THIS

      // ...any other types you might have...
    ],
  ...
}

⚠ ATTENTION: If you have typeRoots configured like this -

"typeRoots": [
  "node_modules/@types"
],

You should add "node_modules" like this -

"typeRoots": [
  "node_modules/@types",
  "node_modules/@hirez_io" // <-- ADD THIS
],

or else it won't find @hirez_io/jest-given global types.

⚠ VS CODE USERS: add the above configuration (types and/or typeRoots) to your tsconfig.json specifically or else it would not recognize the global types.

Prior Art + Credit

This library is a port of @hirez_io/jasmine-given which is a rewrite of the original jasmine-given library by Justin Searls who've done an amazing job with it. Checkout his company TestDouble and their blog.

So why a rewrite and how is it different?

Everything is explained here 😀

Why choose this over plain `beforeEach` and `it()` functions?

✅ Cleaner structure:

Helps you break down tests into the natural "Arrange, Act, Assert" model via "Given When and Then" and by that enforces a "microtest" structure.

describe('MyComponent', () => {
  let firstNum;
  let actualResult;

  // THIS IS EXACTLY LIKE A `beforeEach`
  // It's where you setup your code / inputs
  Given(() => {
    firstNum = 1;
  });

  // THIS IS A SPECIAL TYPE OF `beforeEach`
  // It's where you call the action under test
  When(() => {
    actualResult = addTwo(firstNum);
  });

  // THIS IS EXACTLY LIKE A `it()`
  // It's where you expect the desired outcome
  Then(() => {
    expect(actualResult).toEqual(3);
  });

  // You can also add a message
  Then('it should be equal to 3', () => {
    expect(actualResult).toEqual(3);
  });
});

It even supports `done` and `async` / `await` -

describe('MyComponent', () => {
  let firstNum;
  let actualResult;

  // Supports "done"
  Given((done) => {
    firstNum = 1;
    done();
    // you can also use done(err) or done.fail(err) if you need to
  });

  // Supports "async/await"
  When(async () => {
    actualResult = await addTwo(firstNum);
  });

  Then(() => {
    expect(actualResult).toEqual(3);
  });
});

✅ Reusability:

By being able to extract the action (When) outside the Given & Then pairs, you are able to reuse the same action and save the same repetitive code.

describe('MyComponent', () => {

  let firstNum;
  let actualResult;

  // Although the "When" is defined before the "Given"
  // it will run between each "Given" and "Then"
  // So it's like a "beforeEach" with special powers
  When(() => {
    console.log('WHEN');
    actualResult = addTwo(firstNum);
  })

  describe('GIVEN initial number is 1 THEN the result should be 3', () => {

    Given(() => {
      console.log('GIVEN #1');
      firstNum = 1;
    })

    Then(() => {
      console.log('THEN #1');
      expect(actualResult).toEqual(3);

    })
  })

  describe('GIVEN initial number is 18 THEN the result should be 20', () => {

    Given(() => {
      console.log('GIVEN #2');
      firstNum = 18;
    })

    Then(() => {
      console.log('THEN #2');
      expect(actualResult).toEqual(20);

    })
  })

})



CONSOLE OUTPUT:
--------------

GIVEN #1
WHEN
THEN #1

GIVEN #2
WHEN
THEN #2

✅ Better test description:

The message for it("should do something", ...) focus specifically on the "outcome" (Then), but moving the description of the test into the describe gives you a chance to write a more descriptive test description.

(as seen above)