04_edges_and_corners.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Edge and corner cases (literally)\n",
    "\n",
    "So far we have been testing simple functions that take, at most, two parameters as arguments. There are no complex algorithms or logic at work, so the functions shouldn't behave differently depending on the input. The failure of these functions is down to our (I mean my) poor programming, rather than anything fundamentally complicated in their workings.\n",
    "\n",
    "In practice, this is often not the case. Functions might require many parameters and their execution and output can vary wildly depending on the input. In many cases there might be a _normal_ range of parameter space where the function output is easy to predict, then other regions where the behaviour can be much more complex. When writing tests it is important that you cover as many cases as possible. You should push the boundaries of your software to make sure that it works as expected across the entire range of input under which it is meant to operate. This is known as having good [_code coverage_](https://en.wikipedia.org/wiki/Code_coverage).\n",
    "\n",
    "Testing extreme values is often referred to as covering _edge_ and _corner_ cases. Typically, edge cases test situations where one parameter is at an extreme, while corner cases test two (or more in a multidimensional problems) edge cases simultaneously. However, sometimes the definition isn't so clear. (The principle of testing unusual input holds, though.)\n",
    "\n",
    "In this section we will make use of the provided `grid` package. This provides functionality for working with cells in a two-dimensional grid, like the 4x4 one shown below. (The values in each cell indicate the `(x, y)` position of the cell within the grid.)\n",
    "\n",
    "|    |    |    |\n",
    "|:--:|:--:|:--:|\n",
    "|(0,3)|(1,3)|(2,3)|(3,3)|\n",
    "|(0,2)|(1,2)|(2,2)|(3,2)|\n",
    "|(0,1)|(1,1)|(2,1)|(3,1)|\n",
    "|(0,0)|(1,0)|(2,0)|(3,0)|\n",
    "\n",
    "Let's import the `Cell` class from the package and see how it works."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from grid import Cell\n",
    "help(Cell)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll now create a `Cell` object that sits in the bulk of the grid and test that its neighbours are correct.\n",
    "\n",
    "```python\n",
    "# grid/test/test_cell.py\n",
    "def test_bulk():\n",
    "    \"\"\" Test that a cell in the bulk of the grid is correct. \"\"\"\n",
    "\n",
    "    # Instantiate a cell in the bulk of a 4x4 grid.\n",
    "    c = Cell(2, 2, 4, 4)\n",
    "\n",
    "    # Make sure that the cell has 4 neighbours.\n",
    "    assert c.neighbours() == 4\n",
    "\n",
    "    # Check the coordinates of the neighbours.\n",
    "    assert c.left()  == (1, 2)\n",
    "    assert c.right() == (3, 2)\n",
    "    assert c.up()    == (2, 3)\n",
    "    assert c.down()  == (2, 1)\n",
    "```\n",
    "\n",
    "Here we've instantiated a cell that sits at position `(2, 2)` in a `4x4` grid. Like python, we choose to index from 0.\n",
    "\n",
    "Now let's check the neighbours of the cell. It should have 4 neighbours: `(1, 2)` to the left, `(3, 2)` to the right, `(2, 1)` below, and `(2, 3)` above.\n",
    "\n",
    "Let's run the unit test with `pytest`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "!pytest grid/test/test_cell.py::test_bulk"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Great, everything worked as expected. But that was easy, we could just work out the neighbours straight from the cell position by just adding and subtracting 1.\n",
    "\n",
    "Now let's check a cell on the left-hand edge of the grid at position `(0, 2)`. This should have 3 neighbours: one to the right, one below, and one above.\n",
    "\n",
    "```python\n",
    "# grid/test/test_cell.py\n",
    "def test_left_edge():\n",
    "    \"\"\" Test that a cell on the left edge of the grid is correct. \"\"\"\n",
    "    \n",
    "    # Instantiate a cell on the left edge of a 4x4 grid.\n",
    "    c = Cell(0, 2, 4, 4)\n",
    "\n",
    "    # Make sure that the cell has 3 neighbours.\n",
    "    assert c.neighbours() == 3\n",
    "\n",
    "    # Check the coordinates of the neighbours.\n",
    "    assert c.left()  == None\n",
    "    assert c.right() == (1, 2)\n",
    "    assert c.up()    == (0, 3)\n",
    "    assert c.down()  == (0, 1)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "!pytest grid/test/test_cell.py::test_left_edge"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Fantastic, it works! The behaviour of the `Cell` object was fundamentally different because of the input (we triggered a different set of conditions).\n",
    "\n",
    "Let's now check a cell at the bottom left-corner. This should only have two neigbours: one to the right, and one above.\n",
    "\n",
    "```python\n",
    "# grid/test/test_cell.py\n",
    "def test_bottom_left_corner():\n",
    "    \"\"\" Test that a cell on the bottom left corner of the grid is correct. \"\"\"\n",
    "\n",
    "    # Instantiate a cell at the bottom left corner of a 4x4 grid.\n",
    "    c = Cell(0, 0, 4, 4)\n",
    "\n",
    "    # Make sure that the cell has 2 neighbours.\n",
    "    assert c.neighbours() == 2\n",
    "\n",
    "    # Check the coordinates of the neighbours.\n",
    "    assert c.left()  == None\n",
    "    assert c.right() == (1, 0)\n",
    "    assert c.up()    == (0, 1)\n",
    "    assert c.down()  == None\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "!pytest grid/test/test_cell.py::test_bottom_left_corner"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once again a different condition has been triggered by our change of input. Here we have tested a corner case.\n",
    "\n",
    "## Integration testing\n",
    "\n",
    "So far we have been testing functions and objects in isolation, so called _unit testing_. However, it is likely that you will write software with multiple objects that need to work together in order to do something useful. The process of checking that different pieces of code work together as intended is often called _integration testing_.\n",
    "\n",
    "The `grid` module also contains a `Grid` class that generates a matrix of `Cell` objects and stores them internally. The user can then manipulate the cells by filling or emptying them. Let's import the class and see how it works."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from grid import Grid\n",
    "help(Grid)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's have a play with the class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "grid = Grid(10, 10)\n",
    "grid.fill(0, 0)\n",
    "assert grid.nFilled() == 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "grid.fill(3, 7)\n",
    "assert grid.nFilled() == 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "grid.empty(0, 0)\n",
    "assert grid.nFilled() == 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "assert grid.cell(3, 7).occupied()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "assert not grid.cell(0, 0).occupied()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Great, it looks like the two classes are working together as expected...\n",
    "\n",
    "# Exercises\n",
    "\n",
    "Here you'll be modifying the following files:\n",
    "\n",
    "* `grid/grid.py`\n",
    "* `grid/test/test_grid.py`.\n",
    "\n",
    "#### Exercise 1\n",
    "\n",
    "Run the unit tests for the entire `grid` package.\n",
    "\n",
    "#### Exercise 2\n",
    "\n",
    "Fix the bug in `grid.py` and verify that the tests pass. Do the tests pass when the grid isn't square?\n",
    "\n",
    "_Hint_: neigbours are checked in the private `_initialiseNeighbours` method.\n",
    "\n",
    "#### Exercise 3\n",
    "\n",
    "Create a new file `grid/test/test_grid.py` to test the `Grid` class. You should test that the `fill` and `empty` functions behave as expected. The rules are that any cell in the grid can only be filled once.\n",
    "\n",
    "#### Exercise 4\n",
    "\n",
    "Fix any bugs that you find and validate that your tests pass.\n",
    "\n",
    "#### Bonus\n",
    "\n",
    "Notice that the `fill` and `empty` methods of the `Grid` class take an optional keyword argument, `debug`. Can you replace the tests that you wrote for Exercise 3 with a method called `_validate`. This should check that the internal state of the `Grid` object is consistent any time the `fill` and `empty` methods are called with the option `debug=True`. This is an alternative way of testing, known as _runtime testing_."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}