hirezio
@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-givenor
npm install -D @hirez_io/jest-givenConfiguring 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)
Contributing
Want to contribute? Yayy! 🎉
Please read and follow our Contributing Guidelines to learn what are the right steps to take before contributing your time, effort and code.
Thanks 🙏
Code Of Conduct
Be kind to each other and please read our code of conduct.
Contributors ✨
Thanks goes to these wonderful people (emoji key):
 Shai Reznik 💻 📖 🤔 🚇 🚧 🧑🏫 👀 ⚠️ |
 WynieCronje 💻 ⚠️ 🚧 |
This project follows the all-contributors specification. Contributions of any kind welcome!
License
MIT
Want to learn more?
