pijamas ~trial-runner

pijamas

---

<img src="https://zardoz89.github.io/pijamas/assets/img/logo-big.png" align="left"/> A BDD assertion library for D.

Forked from Yamadacpc's Pyjamas

Example

import pyjamas;

10.should.equal(10);
5.should.not.equal(10);
[1, 2, 3, 4].should.include(3);

Introduction

Pyjamas, and by extension Pijamas, is an assertion library heavily inspired by visionmedia'ś should.js module for Node.JS.

General Assertions

Pijamas exports a single function should meant for public use. Because of D's lookup shortcut syntax, one is able to use both should(obj) and obj.should to get an object wrapped around an Assertion instance.

.be .as .of .a .and .have .which

These methods all are aliases for an identity function, returning the assertion instance without modification. This allows one to have a more fluent API, by chaining statements together:

10.should.be.equal(10);
[1, 2, 3, 4].should.have.length(4);

Assertion not()

This function negates the wrapper assertion. With it, one can express fluent assertions without much effort:

10.should.not.equal(2);

T equal(U)(U other, string file = __FILE__, size_t line = __LINE__);

Asserts for equality between two objects. Returns the value wrapped around the assertion.

[1, 2, 3, 4].should.equal([1, 2, 3, 4]);
255.should.equal(10); // Throws an Exception "expected 255 to equal 10"

T approxEqual(U)(U other, U maxRelDiff = CommonDefaultFor!(T,U), U maxAbsDiff = 0.0, string file = __FILE__, size_t line = __LINE__);

Asserts for approximated equality of float types. Returns the value wrapped around the assertion. See Phobos std.math.isClose().

(1.0f).should.be.approxEqual(1.00000001);
(1.0f).should.not.be.approxEqual(1.01);

T close(U)(U other, U maxRelDiff = CommonDefaultFor!(T,U), U maxAbsDiff = 0.0, string file = __FILE__, size_t line = __LINE__);

Alias of approxEqual

T exist(string file = __FILE__, size_t line = __LINE__);

Asserts whether a value exists - currently simply compares it with null, if it is convertible to null (actually strings, pointers and classes). Returns the value wrapped around the assertion.

auto exists = "I exist!";
should(exists).exist;
string doesntexist;
doesntexist.should.exist; // Throws an Exception "expected null to exist"

bool biggerThan(U)(U other, string file = __FILE__, size_t line = __LINE__);

Asserts if a value is bigger than another value. Returns the result.

"z".should.be.biggerThan("a");
10.should.be.biggerThan(1);

bool biggerOrEqualThan(U)(U other, string file = __FILE__, size_t line = __LINE__);

Asserts if a value is bigger or euqal than another value. Returns the result.

10.should.be.biggerOrEqualThan(1);
10.should.be.biggerOrEqualThan(10);

bool smallerThan(U)(U other, string file = __FILE__, size_t line = __LINE__)

Asserts if a value is smaller than another value. Returns the result.

10.should.be.smallerThan(100);
false.should.be.smallerThan(true);

bool smallerOrEqualThan(U)(U other, string file = __FILE__, size_t line = __LINE__)

Asserts if a value is smaller or equal than another value. Returns the result.

10.should.be.smallerOrEqualThan(100);
10.should.be.smallerOrEqualThan(10);

U include(U)(U other, string file = __FILE__, size_t line = __LINE__);

Asserts for an input range wrapped around an Assertion to contain/include a value.

[1, 2, 3, 4].should.include(3);
"something".should.not.include('o');
"something".should.include("th");

U length(U)(U length, string file = __FILE__, size_t line = __LINE__);

Asserts for the .length property or function value to equal some value.

[1, 2, 3, 4].should.have.length(4);
"abcdefg".should.have.length(0);
// ^^ - Throws an Exception "expected 'abcdefg' to have length of 0"

bool empty(string file = __FILE__, size_t line = __LINE__);

Asserts that the .lenght property or function value is equal to 0;

[].should.be.empty;
"".should.be.empty;

auto match(RegEx)(RegEx re, string file = __FILE__, size_t line = __LINE__);

Asserts for a string wrapped around the Assertion to match a regular expression.

"something weird".should.match(`[a-z]+`);
"something weird".should.match(regex(`[a-z]+`));
"something 2 weird".should.not.match(ctRegex!`^[a-z]+$`));
"1234numbers".should.match(`[0-9]+[a-z]+`);
"1234numbers".should.not.match(`^[a-z]+`);

bool True(string file = __FILE__, size_t = line = __LINE__); and .False

Both functions have the same signature. Asserts for a boolean value to be equal to true or to `false.`

true.should.be.True;
false.should.be.False;

bool sorted(string file = __FILE__, size_t line = __LINE__);

Asserts whether a forward range is sorted.

[1, 2, 3, 4].should.be.sorted;
[1, 2, 0, 4].should.not.be.sorted;

void key(U)(U other, string file = __FILE__, size_t line = __LINE__);

Asserts for an associative array to have a key equal to other.

["something": 10].should.have.key("something");

void Throw(T : Throwable)(string file = __FILE__, size_t line = __LINE__);

Asserts whether a callable object wrapped around the assertion throws an exception of type T.

void throwing()
{
  throw new Exception("I throw with 0!");
}

should(&throwing).Throw!Exception;

void notThrowing()
{
  return;
}

should(&notThrowing).not.Throw;

An example of failing an assertion

<img src="https://zardoz89.github.io/pijamas/assets/img/error.png" />

A failing assertation throws an Exception with information of what was expected, and file and line number where it failed

Need more documentation?

I know the documentation is still somewhat lacking, but it's better than nothing, I guess? :)

Try looking at the test suite in tests/pyjamas_spec.d to see some "real world" testing of the library. Even though we are using Silly testing runner, this library is supposed to be framework agnostic.

BTW, I'll be glad to accept help in writting the documentation.

Tests

Run tests with:

dub test

Why 'Pijamas'

The original project was name "Pyjamas", a name that could be confuse, and have name clash on search engines, with Python's Pyjamas framework. So a new name sees a good idea. Pijamas is the word on Spanish and English for "Pyjamas", so it's a start. If anyone have a better name, hurry up to suggest it.

License

This code is licensed under the MIT license. See the LICENSE file for more information.