guinness2 0.0.5

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 46

Guinness2 Build Status

Guinness2 is a port of the Jasmine library to Dart. It is based on the AngularDart implementation of Jasmine, and similar to Guinness but for dart:test instead of dart:unittest.

Difference from Guinness

Backed by dart:test instead of dart:unittest. Run via pub run test instead of a Karma setup.

Removed bits referring to 'runner' programatically - just use pub run test. Removed deprecated showStats option. Remove all context-keeping, as this is now handles by package:test directly.

Installation

You can find the Guinness installation instructions here.

Importing the Library

import 'package:guinness2/guinness2.dart';

main() {
  // your specs
}

If you are testing a client-side application, and you want to use html matchers, import the guinness_html library.

import 'package:guinness2/guinness2_html.dart';

main() {
  guinnessEnableHtmlMatchers();
  // your specs
}

Syntax

Guinness specs are comprised of describe, it, beforeEach, and afterEach blocks.

import 'package:guinness2/guinness2.dart';

main() {
  describe("syntax", () {
    beforeEach(() {
      print("outer before");
    });

    afterEach(() {
      print("outer after");
    });

    it("runs first", () {
      print("first");
    });

    describe("nested describe", () {
      beforeEach(() {
        print("inner before");
      });

      afterEach(() {
        print("inner after");
      });

      it("runs second", () {
        print("second");
      });
    });
  });
}

This will print:

outer before, first, outer after
outer before, inner before, second, inner after, outer after
  • To exclude a describe, change it to xdescribe.
  • To exclude an it, change it to xit.
  • To make a describe exclusive, change it to ddescribe.
  • To make an it exclusive, change it to iit.
  • Important: to run exclusive tests, add --tags solo to your command line invocation.

Pending Specs

Guinness supports pending describe and it blocks (blocks without a callback).

describe("pending describe");
xdescribe("pending xdescribe");

it("pending it");
xit("pending xit");

Async

Since Dart has built-in futures, the Guinness framework makes a good use out of them. If you return a future from beforeEach, afterEach, or it, the framework will wait for that future to be resolved.

For instance:

beforeEach(connectToTheDatabase);

where connectToTheDatabase returns a future.

Similarly, you can write:

afterEach(releaseConnection);

You can also write async specs using the following technique:

it("should return an empty list when the database is empty", () {
  return queryDatabase().then((results){
    expect(results).toEqual([]);
  });
});

If a returned future gets rejected, the test fails.

Expect

They way you write assertions in Guinness is by using the expect function, as follows:

expect(2).toEqual(2);

These are a few examples:

expect(2).toEqual(2);
expect([1,2]).toContain(2);
expect(2).toBe(2);
expect(()=> throw "BOOM").toThrow();
expect(()=> throw "BOOM").toThrow("BOOM");
expect(()=> throw "Invalid Argument").toThrowWith(message: "Invalid");
expect(()=> throw new InvalidArgument()).toThrowWith(anInstanceOf: InvalidArgument);
expect(()=> throw new InvalidArgument()).toThrowWith(type: ArgumentException);
expect(false).toBeFalsy();
expect(null).toBeFalsy();
expect(true).toBeTruthy();
expect("any object").toBeTruthy();
expect("any object").toBeDefined();
expect(null).toBeNull();
expect("not null").toBeNotNull();

expect(2).not.toEqual(1);
expect([1,2]).not.toContain(3);
expect([1,2]).not.toBe([1,2]);
expect((){}).not.toThrow();
expect(null).not.toBeDefined();

expect(new DocumentFragment.html("<div>some html</div>"))
    .toHaveHtml("<div>some html</div>");

expect(new DocumentFragment.html("<div>some text</div>"))
    .toHaveText("some text");

expect(new DivElement()..classes.add('abc'))
    .toHaveClass("abc");

expect(new DivElement()..attributes['attr'] = 'value')
    .toHaveAttribute("attr");

expect(new DocumentFragment.html("<div>some html</div>"))
    .not.toHaveHtml("<div>some other html</div>");

expect(new DocumentFragment.html("<div>some text</div>"))
    .not.toHaveText("some other text");

expect(new DivElement()..classes.add('abc'))
    .not.toHaveClass("def");

expect(new DivElement()..attributes['attr'] = 'value')
    .not.toHaveAttribute("other-attr");

final select = new SelectElement();
select.children
  ..add(new OptionElement(value: "1"))
  ..add(new OptionElement(value: "2", selected: true))
  ..add(new OptionElement(value: "3"));
expect(select).toEqualSelect(["1", ["2"], "3"]);

You can also use unittest matchers, like this:

expect(myObject).to(beValid); // where beValid is a unittest matcher

Migrating from Unittest/Test

To make migration from the unittest library to Guinness easier, expect supports an optional second argument.

expect(myObject, beValid); // same as expect(myObject).to(beValid);

This keeps your unittest assertions working, so you can change them one by one.

Spy

Guinness supports Jasmine-like spy functions:

final s = guinness.createSpy("my spy");
expect(s).not.toHaveBeenCalled();

s(1);
expect(s).toHaveBeenCalled();
expect(s).toHaveBeenCalledOnce();
expect(s).toHaveBeenCalledWith(1);
expect(s).toHaveBeenCalledOnceWith(1);
expect(s).not.toHaveBeenCalledWith(2);

s(2);
expect((){
  expect(s).toHaveBeenCalledOnce();
}).toThrow();

expect((){
  expect(s).toHaveBeenCalledOnceWith(1);
}).toThrow();

In addition, Guinness support spy objects:

class SomeSpy extends SpyObject implements SomeInterface {}

...

final s = new SomeSpy();
s.invoke(1,2);
s.name;
s.name = 'some name';

expect(s.spy("invoke")).toHaveBeenCalled();
expect(s.spy("get:name")).toHaveBeenCalled();
expect(s.spy("set:name")).toHaveBeenCalled();

And:

final s = new SomeSpy();
s.spy("invoke").andCallFake((a,b) => a + b);

expect(s.invoke(1,2)).toEqual(3);

You can also use the mock and dart_mocks libraries with it.

Implementation Details

Key Ideas

Dart's package:test supports most of the original Guinness test organization natively, so we simply forward to the appropriate package:test function.

The large exception is expectations, matchers, and spies, which are unchanged from original Guinness.

v0.0.5 (2016-03-02)

  • Fixed equality check for nested lists.

v0.0.4 (2016-02-11)

  • BREAKING CHANGE: iit and ddescribe NO LONGER modify which tests will run. Instead, they will mark those blocks with the tag "solo". To run only iit or ddescribe blocks, use the command line pub run test --tags solo (the same command you would use before, with the additional tags "solo").

  • Update pub dependencies

  • Remove all context keeping track of describe and it blocks, instead defer directly to package:test methods.

  • Add a bunch of integration tests.

v0.0.2 (2015-07-23)

  • Fix a bug where some it blocks would still be called when using nested describes.

v0.0.1 (2015-07-20)

  • Initial release: Cloned from Guinness and made to adapt to dart:test

example/example.dart

@TestOn('browser')

library example;

import 'package:guinness2/guinness2_html.dart';
import 'dart:html';

class TestClass {}

main() {
  guinnessEnableHtmlMatchers();

  describe("guinness2", () {
    it("has various built-in matchers", () {
      expect(2).toEqual(2);

      expect([1, 2]).toContain(2);

      expect(2).toBe(2);

      expect(2).toBeA(num);

      expect(1).toBeLessThan(2);
      expect(2).toBeGreaterThan(1);
      expect(1.234).toBeCloseTo(1.23, 2);

      expect(new TestClass()).toBeAnInstanceOf(TestClass);
      expect("sfs").not.toBeAnInstanceOf(TestClass);
      expect(() => throw "BOOM").toThrowWith();
      expect(() => throw "BOOM").toThrowWith(message: "BOOM");
      expect(() => throw "BOOM").toThrowWith(message: new RegExp("B[O]{2}M"));
      expect(() => throw new TestClass()).toThrowWith(anInstanceOf: TestClass);
      expect(() => throw new TestClass()).toThrowWith(type: TestClass);
      expect(() => throw new TestClass()).toThrowWith(where: (e) {
        expect(e).toBeDefined();
      });
      expect(false).toBeFalsy();
      expect(null).toBeFalsy();
      expect(true).toBeTruthy();
      expect("any object").toBeTruthy();
      expect(false).toBeFalse();
      expect(true).toBeTrue();
      expect("any object").toBeDefined();
      expect(null).toBeNull();
      expect("not null").toBeNotNull();

      expect(2).not.toEqual(1);

      expect([1, 2]).not.toContain(3);

      expect([1, 2]).not.toBe([1, 2]);

      expect(() {}).not.toThrow();

      expect(null).not.toBeDefined();

      expect(1).not.toBeLessThan(0);
      expect(0).not.toBeGreaterThan(1);
      expect(1.234).not.toBeCloseTo(1.23, 3);

      expect(new DocumentFragment.html("<div>some html</div>"))
          .toHaveHtml("<div>some html</div>");

      expect(new DocumentFragment.html("<div>some text</div>"))
          .toHaveText("some text");

      expect(new DivElement()..classes.add('abc')).toHaveClass("abc");

      expect(new DivElement()..attributes['attr'] = 'value')
          .toHaveAttribute("attr");

      expect(new DocumentFragment.html("<div>some html</div>")).not
          .toHaveHtml("<div>some other html</div>");

      expect(new DocumentFragment.html("<div>some text</div>")).not
          .toHaveText("some other text");

      expect(new DivElement()..classes.add('abc')).not.toHaveClass("def");

      expect(new DivElement()..attributes['attr'] = 'value').not
          .toHaveAttribute("other-attr");

      final select = new SelectElement();
      select.children
        ..add(new OptionElement(value: "1"))
        ..add(new OptionElement(value: "2", selected: true))
        ..add(new OptionElement(value: "3"));

      expect(select).toEqualSelect(["1", ["2"], "3"]);
    });

    describe("spy", () {
      it("supports spy functions", () {
        final s = guinness.createSpy("my spy");
        expect(s).not.toHaveBeenCalled();

        s(1);
        expect(s).toHaveBeenCalled();
        expect(s).toHaveBeenCalledOnce();
        expect(s).toHaveBeenCalledWith(1);
        expect(s).toHaveBeenCalledOnceWith(1);
        expect(s).not.toHaveBeenCalledWith(2);

        s(2);
        expect(() {
          expect(s).toHaveBeenCalledOnce();
        }).toThrowWith();

        expect(() {
          expect(s).toHaveBeenCalledOnceWith(1);
        }).toThrowWith();
      });
    });

    describe("beforeEach", () {
      var res = [];
      beforeEach(() {
        res.add("outer");
      });

      describe("nested describe", () {
        beforeEach(() {
          res.add("inner");
        });

        it("run callbacks in order", () {
          expect(res).toEqual(["outer", "inner"]);
        });
      });
    });

    describe("afterEach", () {
      var res = [];

      afterEach(() {
        res.add("outer");
      });

      describe("nested describe", () {
        afterEach(() {
          res.add("inner");
        });

        it("will run afterEach after this test", () {});

        it("runs callbacks in reverse order", () {
          expect(res).toEqual(["inner", "outer"]);
        });
      });
    });

    xdescribe("won't run", () {
      it("won't run", () {
        throw "Won't Run!";
      });
    });

    xit("won't run", () {
      throw "Won't Run!";
    });

    it("pending spec");
    describe("pending describe");

    //also supports ddescribe, and iit
  });
}

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  guinness2: "^0.0.5"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:guinness2/guinness2.dart';
        
Version Uploaded Documentation Archive
0.0.5 Mar 2, 2016 Go to the documentation of guinness2 0.0.5 Download guinness2 0.0.5 archive
0.0.4 Feb 11, 2016 Go to the documentation of guinness2 0.0.4 Download guinness2 0.0.4 archive
0.0.3 Jul 24, 2015 Go to the documentation of guinness2 0.0.3 Download guinness2 0.0.3 archive
0.0.2 Jul 23, 2015 Go to the documentation of guinness2 0.0.2 Download guinness2 0.0.2 archive
0.0.1 Jul 22, 2015 Go to the documentation of guinness2 0.0.1 Download guinness2 0.0.1 archive

Analysis

This feature is new.
We welcome feedback.
More details: scoring.

We analyzed this package, and provided a score, details, and suggestions below.

  • tool failures on Feb 14, 2018
  • Dart: 2.0.0-dev.20.0
  • pana: 0.10.1

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
37 / 100
Health:
Code health derived from static analysis. [more]
91 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
4 / 100
Overall score:
Weighted score of the above. [more]
46

Platforms

Detected platforms: web, other

Primary library: package:guinness2/guinness2.dart with components: mirrors.

Suggestions

  • Fix lib/src/common/test_backend.dart.

    Strong-mode analysis of lib/src/common/test_backend.dart failed with the following error:

    line: 32 col: 3
    Invalid override. The type of 'TestMatchers.toThrow' ('(dynamic, [Pattern]) → void') isn't a subtype of 'Matchers.toThrow' ('(dynamic, dynamic) → void').

  • Fix issues reported by dartanalyzer.

    dartanalyzer reported 1 error(s) and 0 warning(s).

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.13.0 <2.0.0
collection >=1.4.0 <2.0.0 1.14.5
test ^0.12.10 0.12.30+3
Transitive dependencies
analyzer 0.31.1 0.31.2-alpha.0
args 1.3.0
async 2.0.3 2.0.4
barback 0.15.2+14
boolean_selector 1.0.2
charcode 1.1.1
cli_util 0.1.2+1
convert 2.0.1
crypto 2.0.2+1
csslib 0.14.1
front_end 0.1.0-alpha.9 0.1.0-alpha.10
glob 1.1.5
html 0.13.2+2
http 0.11.3+16
http_multi_server 2.0.4
http_parser 3.1.1
io 0.3.2+1
isolate 1.1.0
js 0.6.1
kernel 0.3.0-alpha.9 0.3.0-alpha.10
logging 0.11.3+1
matcher 0.12.1+4
meta 1.1.2
mime 0.9.6
multi_server_socket 1.0.1
node_preamble 1.4.0
package_config 1.0.3
package_resolver 1.0.2
path 1.5.1
plugin 0.2.0+2
pool 1.3.4
pub_semver 1.3.2
shelf 0.7.2
shelf_packages_handler 1.0.3
shelf_static 0.2.7
shelf_web_socket 0.2.2
source_map_stack_trace 1.1.4
source_maps 0.10.4
source_span 1.4.0
stack_trace 1.9.2
stream_channel 1.6.3
string_scanner 1.0.2
term_glyph 1.0.0
typed_data 1.1.5
utf 0.9.0+4
watcher 0.9.7+7
web_socket_channel 1.0.6 1.0.7
yaml 2.1.13
Dev dependencies
mockito 0.11.0