Readme.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# jest\n",
    "\n",
    "Jest enables you to embed tests in the same file as the code it tests. This makes for a really nice interactive development workflow and can help the reader understand your code\n",
    "\n",
    "## Installation\n",
    "\n",
    "```sh\n",
    "git clone https://github.com/jkroso/Jest.jl.git\n",
    "make -C jest install\n",
    "```\n",
    "\n",
    "This will make the `jest` binary available from your shell. If you want to make Jest's functions globally available and therefore feel like they were built into Julia then you just need to require it in you ~/.juliarc.jl file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "@require \"github.com/jkroso/jest\" test @catch @test;"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## API\n",
    "\n",
    "### @test\n",
    "\n",
    "Takes an expression and runs it returning a `Result` which tells you how long the expression took to evaluate and whether or not it returned `true` or `false`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"padding:1px 5px;font-size:14px;color:rgb(0, 226, 0);\">✓ 1ms</div>"
      ],
      "text/plain": [
       "✓ 1ms"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@test true"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`true` is considered a passed test."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"padding:1px 5px;font-size:14px;color:red;\">✗ 1ms</div>"
      ],
      "text/plain": [
       "✗ 1ms"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@test false"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While `false` denotes a failiure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### @catch\n",
    "\n",
    "Takes an expression that throws an error, catches it and returns it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ErrorException(\"boom\")"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@catch error(\"boom\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This makes it possible to then use normal assertions to ensure the correct errors are thrown"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"padding:1px 5px;font-size:14px;color:rgb(0, 226, 0);\">✓ 13ms</div>"
      ],
      "text/plain": [
       "✓ 13ms"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@test isa(@catch(error(\"boom\")), ErrorException)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the expression does not throw an error and error is thrown"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "ename": "LoadError",
     "evalue": "LoadError: did not throw an error\nwhile loading In[6], in expression starting on line 72",
     "output_type": "error",
     "traceback": [
      "LoadError: did not throw an error\nwhile loading In[6], in expression starting on line 72",
      "",
      " in error at /opt/homebrew-cask/Caskroom/julia/0.4.2/Julia-0.4.2.app/Contents/Resources/julia/lib/julia/sys.dylib"
     ]
    }
   ],
   "source": [
    "@catch ErrorException(\"that I forgot to throw\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### test(f::Function, title::String)\n",
    "\n",
    "`test` provides a way of grouping assertions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"padding:1px 5px;font-size:14px;color:red;\">✗ 232ms</div>"
      ],
      "text/plain": [
       "✗ 232ms"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "test(\"something thats broken\") do\n",
    "  @test true\n",
    "  @test false\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The result will be a passed assertion only if all the assertions contained in `f` pass."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"padding:1px 5px;font-size:14px;color:rgb(0, 226, 0);\">✓ 6ms</div>"
      ],
      "text/plain": [
       "✓ 6ms"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "test(\"something that works\") do\n",
    "  @test true\n",
    "  @test true\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Groupings can also be nested arbitrarily deep. Which provides a good way to test complicated functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div style=\"padding:1px 5px;font-size:14px;color:rgb(0, 226, 0);\">✓ 8ms</div>"
      ],
      "text/plain": [
       "✓ 8ms"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "test(\"something complicated\") do\n",
    "  @test true\n",
    "  test(\"that has edge cases\") do\n",
    "    @test true\n",
    "  end\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Examples\n",
    "\n",
    "See [test.jl](test.jl) for a more complete set of API examples. It can be run with `$ ./bin/jest test`"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Julia 0.4.2",
   "language": "julia",
   "name": "julia-0.4"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "0.4.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}