Roadmap

  • Double-check you are ready to get going
  • Introduction to Mixes
  • Running Tests with Mixes
    • Running all the tests
    • Running all tests in a file
    • Running only 1 test in a file
  • Mixes in IEx
  • Where to next?

Ready to get going?

This assumes you already have Elixir and Atom installed for your platform. If not, see this post for getting started.

Introducing the Elixir “Mix”

While IEx is super cool, it gets even better once we go a little further. In order to better learn a language and the whole Erlang/Elixir framework, I need a simple project. Conveniently, Elixir has the “mix” command built-in. This is helpful for starting a new Elixir project that follows good practices on project layout and starts you off right with tests built-in. Some of this was taken from the Introduction to Mix.

$ mix new test_project

* creating README.md
* creating .gitignore
* creating mix.exs
* creating config
* creating config/config.exs
* creating lib
* creating lib/test_project.ex
* creating test
* creating test/test_helper.exs
* creating test/test_project_test.exs

Your Mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd test_project
    mix test

Run "mix help" for more commands.

Running Tests

The default mix new project has a single passing test as an example. Run the tests to see the output.

$ cd test_project
$ mix test

Compiled lib/test_project.ex
Generated test_project app
.

Finished in 0.09 seconds (0.09s on load, 0.00s on tests)
1 test, 0 failures

Randomized with seed 153170

The “dot” on a line by itself shows that 1 test was run and passed. Let’s see what that was.

Examine our tests

In Atom, open the folder for our mix project.

test/test_project_test.exs

defmodule TestProjectTest do
  use ExUnit.Case
  doctest TestProject

  test "the truth" do
    assert 1 + 1 == 2
  end
end

What “Failure” looks like:

Create a failing test. Edit, “test/test_project_test.exs” adding test "failure".

defmodule TestProjectTest do
  use ExUnit.Case
  doctest TestProject

  test "the truth" do
    assert 1 + 1 == 2
  end

  test "failure" do
    assert 1 + 1 == 3
  end
end

In a terminal, run “mix text” again:

$ mix test
.

  1) test false (TestProjectTest)
     test/test_project_test.exs:9
     Assertion with == failed
     code: 1 + 1 == 3
     lhs:  2
     rhs:  3
     stacktrace:
       test/test_project_test.exs:10



Finished in 0.05 seconds (0.05s on load, 0.00s on tests)
2 tests, 1 failure

Randomized with seed 708408

The “dot” by itself is still there showing one test ran and passed. Now it is followed by output for a failing test. Nice! It shows the code being tested, the “lhs” for “left-hand-side” of the equation and “rhs” for “right-hand-side”. Then stacktrace gives us the line number where it failed.

Running a specific file

In larger projects, you don’t want to run all your tests every time. You can run just a specific file.

$ mix test test/test_project_test.exs
.

Finished in 0.05 seconds (0.05s on load, 0.00s on tests)
1 test, 0 failures

Randomized with seed 561340

Running a specific test

Running a specific test that you are working on is also easy. You do this by specifying the file to run and adding the line number. For this example I added a couple more failing tests to the file to show that 2 were skipped. But the output isn’t cluttered with all the noise of failing tests that I’m not working on yet.

$ mix test test/test_project_test.exs:5
Including tags: [line: "5"]
Excluding tags: [:test]

.

Finished in 0.06 seconds (0.06s on load, 0.00s on tests)
3 tests, 0 failures, 2 skipped

Randomized with seed 562760

Mix in IEx

Now that we have a mix, IEx can get even better! Working with your project in IEx is helpful for interactively testing and playing with your code.

First lets add some code that we can call.

In our mix project, edit lib/test_project.ex to add a say_hello function.

defmodule TestProject do

  def say_hello do
    IO.puts "Hello everyone!"
  end

end

Interact with the Mix in IEx

From within your mix project folder…

$ iex -S mix

We can now start typing “TestProject” and hit “tab” to complete it.

Tes<tab> -> TestProject.

Tab can complete the functions available on a module…

TestProject.<tab>
Mixfile        say_hello/0    
TestProject.say_hello
Hello everyone!
:ok

Recompile within IEx for Code Change

Made a code change and you want to test it out in IEX? To pickup the change you tell the terminal to recompile. Note: this requires iex -S mix.

iex(1)> recompile

07:21:27.679 [info]  Application test_project exited: :stopped
{:restarted, [:test_project]}

Now we have Mix projects for building projects with best practice organization, a place for tests and an easy way to run them! We’re ready to to start digging into Elixir more deeply.

Next Step…

Now I just want my development environment setup. Next we’ll setup the Atom Editor for Elixir development.