Getting Started

This document will guide you through the basics of Alright. This is a quick introduction, but once you finish this page you’ll know all you need to start writing assertions for your code-base.

What is Alright?

Alright is a library that provides ways of asserting properties about pieces of data in JavaScript without verbosity, and in a way that it can be easily extended to support specific type of assertions. It also provides Sweet.js macros for writing concise assertions.

For example:

2 + 2 => 4
[1, 2, 3] should have('foo')

Okay, cool. Where do I start?

In this tutorial we’re going to use Alright together with Node.js, Mocha, and Sweet.js to write some tests. The process is pretty similar to all other platforms, and we show how to make things work in the browser at the end.

So, first things first, once you’ve got Node.js installed, you’ll want to start a new project and run the following commands:

$ mkdir test-project
$ cd test-project
$ npm install sweet.js alright mocha

Writing assertions

With all in place, we’re ready to create our first test script. Make a file test/array.sjs with the following contents:

// The only requirement is that you have `alright` in your
// scope for the macros to work.
var alright = require('alright')

describe('Array#indexOf()', function() {
  it('Should return the index of the item.', function() {
    [1, 2, 3].indexOf(2) => 1
  })

  it('Should return -1 if the item is not present.', function() {
    [1, 2, 3].indexOf(4) => -1
  })
})

As you see, assertions are written in using the form: expression => expected, where expression is any computation for the value you want to test, and expected is the value you expect to get as result. The values are compared structurally, which means that [1, 2, 3] => [1, 2, 3] will succeed, for example. You can use expression => not expected to invert the expectation, so 2 => not 1 will succeed.

The keen JavaScripter might have noticed that we’re not quite writing JavaScript here, so first we need to turn this script into something a JS engine (in this case, Node’s v8) will understand. This is where the sjs compiler we’ve installed (through sweet.js) comes in. It takes a .sjs file, some macro definitions (which do tell the compiler how the magic should be done), and gives us JavaScript as we know it:

$ $(npm bin)/sjs --module alright/macros -o test/array.js test/array.sjs

Note

The $(npm bin) command allows one to get the path where local binaries are installed with npm, so you can use it to keep all of your dependencies localised instead of installing them globally.

Finally, we just need to run the test through Mocha:

$ $(npm bin)/mocha --reporter spec

Should all go well, you’ll see the following output:

Note

If you’re not using any build system, you can get npm to help you with automating this compiling/testing phase. Just put whatever you’d write in the command line inside of your package.json‘s script section. You can even leave out the $(npm bin) part, since npm searches inside that folder automagically:

{
  ( ... )
  "scripts": {
    "test-cc": "sjs -m alright/macros -o test/array.js test/array.sjs",
    "test": "npm run test-cc && mocha --reporter spec"
  },
  ( ... )
}

Complex assertions

The most straight forward way of making assertions is the structural equality assertion (=>), but sometimes you’re interested in other properties as well. There are so many possibilities of properties you can come up with that it doesn’t make sense to come up with a special symbol for every one of them. So, instead, Alright allows you to provide a validation function.

Many validations are built right into Alright itself. In fact, the structural equality assertion is just a special case of this:

[1, 2] => [1, 2]
// Is the same as:
[1, 2] should alright.equal([1, 2])

Since they’re just regular functions, you can always write your own:

function beGreater(expected){ return function(actual) {
  var divergence = alright.divergence.invertibleDivergence(
    '{:actual} to be greater than {:expected}'
  , '{:actual} to not be greater than {:expected}'
  )

  return alright.assert( actual > expected
                       , divergence.make({ actual  : actual
                                         , expected: expected }))
}}

3 should beGreater(2)

Other platforms

The same concepts explained here apply to all other JavaScript platforms, but if you’re not using a platform that has direct support for Node modules, you’ll want to use the UMD bundle (the single file that can be used in any platform, and any module system!). The easiest way of doing so is downloading the latest release and loading the alright.umd.js in your platform:

Common JS:

var alright = require('alright')
( ... )

AMD:

require(['alright'], function(alright) {
  ( ... )
})

Browser without a module system:

<script src="/path/to/alright.umd.js"></script>
<script>
  /* alright is in the global scope here */
  ( ... )
</script>

Using Alright without macros

If you don’t want to use Sweet.js macros, you can use alright’s testing functions directly. Just use the verify function to throw an exception if an expectation isn’t met:

var _ = alright


_.verify( _.equals(1)(1) )          // same as: 1 => 1

_.verify( _.not(_.equals(1)(1)) )   // same as: 1 => not 1

Where to go from here?

Now that you get the idea behind Alright, you can start writing your assertions for testing your JavaScript code. Be sure to check out the Discover Alright documentation to learn everything you can get from the library.