resolves merge conflicts #21

README.md

@@ -3,6 +3,19 @@
 Learn the Elixir _language_, designed to build dynamic, functional,
 scalable and maintainable web applications!
 
+## Contents
+- [Why?](#why)
+- [What?](#what)
+- [How?](#how)
+- [Handy Tips](#handy-tips)
+- [Basic Types](#basic-types)
+- [Functions and Modules](#functions-and-modules)
+- [Generate an Elixir Project](#generating-your-first-elixir-project)
+- [Documentation](#documentation)
+- [Testing](#testing)
+- [Data Structures](#data-structures)
+  - [Maps](#maps)
+
 ## *Why*?
 
 Elixir is scalable, efficient, and fault-tolerant. Things *will* go wrong with
@@ -31,6 +44,7 @@ so "**real-time**" web apps are "_easy_"
 (_or at least **easier** than many other languages!_)
 + ***Zero-Downtime Deployment*** is a _reality_ without any DevOps gymnastics!!!
 
+***
 
 ## *What*?
 
@@ -73,6 +87,7 @@ https://www.sitepoint.com/an-interview-with-elixir-creator-jose-valim/
 + What was "_wrong_" with just writing directly in Erlang? read:
 http://www.unlimitednovelty.com/2011/07/trouble-with-erlang-or-erlang-is-ghetto.html
 
+***
 
 ## *How*?
 
@@ -118,6 +133,9 @@ type `i` followed by the value name:
 
 ![elixir-i](https://cloud.githubusercontent.com/assets/14013616/20860322/3c01d984-b96d-11e6-8cc4-a46c8657f5b4.png)
 
+***
+
+
 ## *Basic Types*
 
 Elixir has 7 basic types:
@@ -315,7 +333,10 @@ A long story short, for large lists or tuples:
 
 > source: http://stackoverflow.com/questions/31192923/lists-vs-tuples-what-to-use-and-when
 
-## Functions and Modules
+***
+
+
+## *Functions and Modules*
 
 ### Anonymous functions
 
@@ -394,8 +415,10 @@ will be available (provided that `iex` is started
 iex> Math.sum(1, 2)
 3
 ```
+***
 
-## Generating your first Elixir project
+
+## *Generating your first Elixir project*
 
 To get started with your first Elixir project you need to make use of the [Mix](https://hexdocs.pm/mix/Mix.html) build tool that comes straight out of the box. Mix allows you to do a number of things including:
 
@@ -636,9 +659,9 @@ def load(filename) do
 end
 ```
 
-#### Pipe Operator. What if we wanted to call some of our functions in succession
-to another. Let's create a function that creates a zoo, randomises it and then
-returns a selected number of animals to go and see:
+#### Pipe Operator
+
+What if we wanted to call some of our functions in succession to another. Let's create a function that creates a zoo, randomises it and then returns a selected number of animals to go and see:
 
 ```elixir
 @doc """
@@ -665,7 +688,10 @@ end
 Now that we have the functionality for our module, let's take a look at the documentation
 that we have written and how we can maximise its use.
 
-## Documentation
+***
+
+
+## *Documentation*
 
 When we created a new project with mix, it created a file for us called `mix.exs`
 which is referred to as the 'MixFile'. This file holds information about our
@@ -708,7 +734,8 @@ documentation (*make sure you're not in `iex`*):
 
 This will generate documentation that can be viewed if you copy the file path of
 the `index.html` file within the newly created `doc` folder and then paste it in
-your browser. You should see something like the following:
+your browser. If you have added documentation to your module and functions as per
+the examples above, you should see something like the following:
 
 ![api](https://cloud.githubusercontent.com/assets/12450298/22835012/260b07f4-efaf-11e6-9704-690c6c245c37.png)
 
@@ -723,6 +750,71 @@ This is an incredibly powerful tool that comes baked-in with elixir. It means th
 other developers who are joining the project can be brought up to speed incredibly
 quickly!
 
+***
+
+
+## *Testing*
+
+When you generate a project with Elixir it automatically gives you a number of
+files and directories. One of these directories is called `test` and it holds two
+files like should have names like:
+- `[project_name]_test.exs`
+- `test_helper.exs`
+
+Our first file was called `animals_test.exs` and it contained some boilerplate that
+looks like:
+
+```elixir
+defmodule AnimalsTest do
+  use ExUnit.Case
+  doctest Animals
+
+  test "the truth" do
+    assert 1 + 1 == 2
+  end
+end
+```
+**NOTE:** It automatically includes a line called `doctest Animals`. What this means
+is that it can run tests from the examples in the documentation that you write for
+your functions
+
+To run the tests enter the following in your terminal:
+`mix test`  
+It should print out whether the tests pass or fail.
+
+Let's add some tests of our own. Firstly let's write a test for the `Animals.randomise`
+function. The reason why we wouldn't want to write a doctest for this is because
+the output value changes everytime you call it. Here's how we would write a test
+for that type of function:
+
+In the `animals_test.exs` file, remove the boilerplate "the truth" test and then
+add this:
+
+```elixir
+test "randomise" do
+  zoo = Animals.create_zoo
+  assert zoo != Animals.randomise(zoo)
+end
+```
+
+**NOTE:** you do not need to install and require any external testing frameworks.
+It all comes with the Elixir package. Simply write `test` followed by a string
+representing what you are trying to test and then write your assertion.
+
+The test above isn't completely air-tight. Elixir provides you with assertions that
+can help deal with things like this. The test could be re-written like so:
+
+```elixir
+test "randomise" do
+  zoo = Animals.create_zoo
+  refute zoo == Animals.randomise(zoo)
+end
+```
+
+This is basically saying "prove to be false that zoo is equal to Animals.randomise(zoo)"
+
+***
+
 ## Data Structures
 
 ### Maps
@@ -797,9 +889,7 @@ iex> %{animals | name: "Max"}
 # %{legs: 4, name: "Max", type: "dog"}
 ```
 **NOTE:** Unlike the function method above, this syntax can only be used to UPDATE
-a current key-value pair inside the map, it cannot add a new key value pair
-
-
+a current key-value pair inside the map, it cannot add a new key value pair.
 
 ## Resources
 

examples/animals/animals.ex

@@ -19,12 +19,6 @@ defmodule Animals do
   @doc """
   randomise takes a list of zoo animals and returns a new randomised list with
   the same elements as the first.
-
-  ## Examples
-
-      iex> zoo = Animals.create_zoo
-      iex> Animals.randomise(zoo)
-      ["monkey", "tiger", "elephant", "gorilla", "giraffe", "lion"]
   """
   def randomise(zoo) do
     Enum.shuffle(zoo)
@@ -99,11 +93,6 @@ defmodule Animals do
   selection takes a number, creates a zoo, randomises it and then returns a list
   of animals of length selected
 
-  ## Examples
-
-      iex> Animals.selection(2)
-      ["gorilla", "giraffe"]
-
   """
   def selection(number_of_animals) do
     Animals.create_zoo