Neverending Package Mountain

    @hirez_io/jasmine-given
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.5 • Public • Published

    @hirez_io/jasmine-given 📃👌

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

    npm version npm downloads codecov Build and optionally publish lerna Code of Conduct License: MIT

    Installation

    yarn add -D @hirez_io/jasmine-given
    

    or

    npm install -D @hirez_io/jasmine-given
    

    Using TypeScript?

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

    // tsconfig.json or tsconfig.spec.json
    
    {
      ...
      "types": [
          "jasmine",
          "@hirez_io/jasmine-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/jasmine-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.

    Using karma?

    @hirez_io/jasmine-given has a dependency on @hirez_io/karma-jasmine-given which is a karma plugin (inspired by karma-jasmine-given) I rewrote to save you the hassle of loading the library script yourself.

    So it will automatically installs @hirez_io/karma-jasmine-given for you 😎

    Here's how to modify your karma.conf.js:

    // karma.conf.js
    
    module.exports = function(config) {
      config.set({
    
        plugins: [
          require('karma-jasmine'),
          require('@hirez_io/karma-jasmine-given'), // <-- ADD THIS
          require('karma-chrome-launcher')
          // other plugins you might have...
        ],
    
        frameworks: [
          '@hirez_io/jasmine-given', // <-- ADD THIS
          'jasmine',
          // other frameworks...
        ],
    
        // ...

    Prior Art + Credit

    This library 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?

    Well.. because the original library is no longer maintained and was written in CoffeeScript, so I decided to rewrite it in TypeScript to make sure I could continue supporting it.

    Plus I fixed the error messages, removed less frequently used features and added support for newer features like async/await etc.

    How is it different from the original jasmine-given?

    IMPROVEMENTS:

    • Better error messages
    • Typescript instead of Coffeescript
    • Add true support for async / await
    • Wrapped sync functions as async to prevent zalgo

    BREAKING CHANGES: I removed a bunch of features that I didn't really use that much over the years which also made this library more complicated to implement.

    • Add() is removed
    • Invariant() is removed

    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.

    License

    MIT

    Install

    npm i @hirez_io/jasmine-given

    DownloadsWeekly Downloads

    1,911

    Version

    1.0.5

    License

    MIT

    Unpacked Size

    45.9 kB

    Total Files

    13

    Last publish

    Collaborators

    • hirez.io