DEV Community: Nick Vernij

Debugging and mocking third party services in Elixir with Mox

Nick Vernij — Wed, 19 May 2021 15:12:42 +0000

Almost every backend application uses them, third party services. Whether it's S3 for object storage, Segment for analytics or Firebase for push notifications. Those services are super helpful and do a lot of heavy-lifting, but in my experience usually do make debugging business logic on your local machine a pain, and testing them isn't easy either.

There are some great solutions available in Elixir. In this post I'm sharing the approach I have been using for the past few years using Elixir. I'll be going over defining behaviours and using them for local debugging during development as well as writing tests.

Defining a behaviour

Interfaces should be familiar for anyone coming from typed object-oriented languages such as Java or TypeScript. Elixir's equivalent of this is called a behaviour. By using type-specs we can define a module's functions in a behaviour, which can be implemented by multiple modules, usually called "callbacks" in Elixir.

If you are unfamiliar with type-specs, I highly recommend this comprehensive blog post by Kevin Peter

For this post's example we want to define a simple behaviour that can send a push notification to a user. We're going to write a behaviour module that will describe the function definitions we need to send push notifications.

In a behaviour, each @callback annotation defines the type-spec of a function that is required on any implementation of this behaviour. For our push notifications use-case the simple behaviour below will do; a single send_push function that takes a User struct as a recipient and a string as a title for the push notification.

defmodule MyApp.Infrastructure.PushBehaviour do
  # Sends a push notification to the given User with the given title.
  # Returns :ok if the message was sent or an :error tuple with an error message.
  @callback send_push(recipient :: MyApp.User.t(), title :: String.t()) ::
              :ok | {:error, String.t()}
end

Stub, Debug and Production implementations

Once we have determined what our behaviour looks like, we can start thinking about what our implementations may look like. I usually end up writing three implementations, one for each Mix environment.

Development: A behavior that helps us debug our business logic locally without depending on secrets or even an internet connection. In the case of push notifications we can simply log the user's name and the message they will be receiving to the Elixir Logger. For other use-cases, like object file storage, we can choose to write/modify/delete files on our local filesystem in a temporary folder instead of to for example Login.
Testing: For testing you want to define a "stub" that doesn't actually do anything with the data, and always acts as if anything you're trying to do is successful. You want to prevent calling your third party vendor hundreds of times while running tests. They may rate-limit you or it may incur costs. In those stubs you always want to return a succesful response, in our case that is :ok, acting as if the push notification was sent succesfully. We'll go over testing error responses from your behaviour later.
Production: This will call the third party service, which may be a library, rest API or whatever. Entirely up to you.

Implementing a behaviour on a callback module is done by adding the @behaviour decorator as well as implementing all of its defined callbacks. Here are some example implementations for our Stub, Debug and Production implementation.

Our stub implementation will always return :ok, it's there mainly to not raise any errors while running tests or compiling your app.


defmodule MyApp.Infrastructure.StubPush do
  @moduledoc """
  Do nothing. Always succeed.
  """

  @behaviour MyApp.Infrastructure.PushBehaviour

  def send_push(_user, _title) do
    :ok
  end
end

Our debug implementation will use Logger to print the recipient's username and the title of the push notification. This is useful when writing your application locally and trying out your code without having to connect to your third party service.

defmodule MyApp.Infrastructure.DebugPush do
  @moduledoc """
  Print a push notification to our logger
  """

  @behaviour MyApp.Infrastructure.PushBehaviour

  require Logger

  def send_push(user, title) do
    Logger.info("Sending a notification to user @#{user.username} with title \"#{title}\"")
    :ok
  end
end

For a production example, I'm assuming we're using a fictional Firebase library for sending notifications. This can be any service or library for your use-case of course.

defmodule MyApp.Infrastructure.FirebasePush do
  @moduledoc """
  Send a push notification through firebase
  """

  @behaviour MyApp.Infrastructure.PushBehaviour

  def send_push(user, title) do
    SomeFirebaseLibrary.some_send_function(user.token, title)
  end
end

Mocking

The go-to library for working with mocks in Elixir is Mox, authored by José Valim. Follow the instructions on their docs to have it installed so we can jump straight into setting up testing for our application's push notification.

First we're going to head over to test_helper.exs in your project. Every Elixir project with tests will have this file generated by default.

We are going to add a mock with Mox.defmock. This generates a module based on the behaviour we pass it. It's important to define a "stub" as well. Mox doesn't know what to return for each function and will error when a function is called without having an implementation. Mox.stub_with will fill those functions with the always-succeeding callbacks we defined in our StubPush module.

# In test/test_helper.exs

# This will generate a module named MyApp.Infrastructure.MockPush
Mox.defmock(MyApp.Infrastructure.MockPush, for: MyApp.Infrastructure.PushBehavior)
# This will define all callbacks
Mox.stub_with(MyApp.Infrastructure.MockPush, MyApp.Infrastructure.StubPush)

ExUnit.start()

We are now ready to start writing the tests for our push notification business logic. To prepare a test module for dealing with mox we need to

add import Mox so we can use Mox's expect functions later on
add setup :verify_on_exit! which will perform some checks about your mocks after a test has run.

defmodule MyApp.PushTest do
  use ExUnit.Case, async: true

  # 1. Import Mox
  import Mox
  # 2. setup fixtures
  setup :verify_on_exit!

  # Here go your tests...
end

In our tests we want to assert two main things:

Are our send_push functions called with the right parameters
Does our application handle errors returned from send_push

In order to do this we have to overwrite our stub behavior with a function specific to said test case. Mox provides the expect function for this, which we imported earlier. expect changes the function body for that specific test. Other tests will still use the stubbed behavior. Let's start with asserting whether the right parameters were given to send_push.

There's a cool blog-post by José Valim detailing the decisions that lead to the design of Mox. I'd recommend reading it if you want to dive a bit deeper.

When verifying parameters, you usually want to depend on pattern matching in Mox's case. With the pin operator (^) we can verify whether send_push was called with the same user as we passed into do_something_that_sends_push. Mox will ensure that your test fails when an expect is never called or when there is no matching function clause.

test "Succesfully sends push notification to right user" do
  # Tip: ExMachina is a great library that helps generate entities like this.
  user = insert(:user)

  MyApp.Infrastructure.MockPush
  # Check if the user on `send_push` is the same user as we passed thru our call below
  # If the user does not match, this will throw a MatchError
  |> expect(:send_push, fn ^user, _title -> :ok end)

  MyApp.do_something_that_sends_push(user)
end

We can also use expect to return an error for send_push and check whether our business logic handles this properly. Let's say we want our do_something_that_sends_push function to propagate the push error to its caller, its test will look something like this:

test "Succesfully propagates errors from push service" do
  # Tip: ExMachina is a great library that helps generate entities like this.
  user = insert(:user)

  MyApp.Infrastructure.MockPush
  # Check if the user on `send_push` is the same user as we passed thru our call below
  # If the user does not match, this will throw a MatchError
  |> expect(:send_push, fn _user, _title -> {:error, "This user does not have push enabled"} end)

  assert MyApp.do_something_that_sends_push(user) == {:error, "This user does not have push enabled"}
end

Tying it all together

These tests won't succeed yet. There is one last step before we can successfully try out our test and debug push implementations. We need to tell our application which implementation of our Push behavior it needs to call in certain environments. To do this we are going to use the Application module which comes with Elixir, and the config files automatically generated in your Elixir project:

# In config/dev.exs we use our push notification logger
config :my_app, :push_api, MyApp.Infrastructure.DebugPush

# In config/test.exs we use our Mock as named in Mox.defmock
config :my_app, :push_api, MyApp.Infrastructure.MockPush

# In config/prod.exs we want to use our Firebase client
config :my_app, :push_api, MyApp.Infrastructure.FirebasePush

Now in any case where you need to send a push notification, you should get the currently configured push implementation from the Application's environment before you call it. You can wrap this in a module if you use the implementation a lot.

# individually
Application.get_env(:my_app, :push_api).send_push(user, "title")

# wrapped in a module
defmodule MyApp.Infrastructure.Push do
  def send_push(user, title) do
    Application.get_env(:my_app, :push_api).send_push(user, title)
  end
end

You can now call MyApp.Infrastructure.Push.send_push, which will look up the PushBehaviour implementation in your Application's environment and call the defined module. Try it out by running iex -S mix and calling the function. For your dev environment it will log a message to the console!

In conclusion

Defining a behaviour and different implementations

Are useful when debugging your app's business logic without having to depend on a third party service on your local machine
Can be used to stub your calls to third party vendors, preventing you from calling them hundreds of times during tests.
Can be used together with Mox to assert whether your app behaves correctly with different responses from your third party vendors' APIs

Thanks for reading, feel free to hit me up on twitter if you have any questions or feedback.

Testing your Elixir + Phoenix + Postgres app with Github CI

Nick Vernij — Thu, 29 Aug 2019 15:38:43 +0000

Originally posted on nickvernij.nl

GitHub released their own CI recently, its UI and marketing look very fancy. I had to set up a new Elixir + Phoenix project and decided to give it a shot.

It took me a full morning to get a green check, because the default elixir template is very minimal and the documentation for creating workflows is quite a lot of reading to get through.

There are some nooks and crannies to get through, but when you get it to work it's very powerful. Essentially, the default Elixir workflow is fine for testing your average Elixir library, however a Phoenix app will need some additional setup and services. In my example I needed to set-up a PostgreSQL service.

First of all we want to set the MIX_ENV environment variable, so when we use ecto, it knows it should setup the test database. We can define global environment variables when defining the container in which our tests will run.

    container:
      image: elixir:1.9.1-slim
      env:
        MIX_ENV: test

Setting up a database

But to use ecto we actually need a database. In the workflow definition we can define a list of services. These are docker images that are prerequisites for our our test steps to run.

This is what my services configuration looks like:

    services:
      postgres:
        image: postgres
        ports:
          - 5432:5432
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_USER: postgres
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 3

Let's go through this service definition rule-by-rule:

image: postgres defines which docker image to pull in, in my case I am using the official docker image for Postgres: https://hub.docker.com/_/postgres

ports:
    - 5432:5432

We always have to define which ports we want to expose for our docker container. In this case I am just exposing the default Postgres port

env:
  POSTGRES_PASSWORD: postgres
  POSTGRES_USER: postgres

The docker container we use has some environment variables defined, which it will use to configure the Postgres server. A full list of those variables can be found in the Postgres Docker Hub description.

options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5

Lastly, we have to pass some additional options. These options will directly map to the docker create command. The reason we need to add this health check is because docker create exits before the container is actually ready to be used.

Luckily for us, there is a simple command pg_isready available, which we can check. As soon as the Postgres container is ready, your test run will continue.

Connecting with the database

The default Elixir workflow should already have some steps defined. We are modifying the Run Tests step a bit so it will create a database and pass some additional environment variables.

All services defined will create a virtual host on the network, named after the service. This means you cannot simply reach the Postgres on localhost.

I have added an environment variable in my run step that exposes the name of the services.

    - name: Run Tests
      run: mix test
      env:
        DB_HOST: postgres

Additionally I modified my Mix test configuration to read this variable and fall back on localhost by default

# Configure your database
config :myapp, MyApp.Repo,
  username: "postgres",
  password: "postgres",
  database: "myapp_test",
  hostname: System.get_env("DB_HOST", "localhost"),
  pool: Ecto.Adapters.SQL.Sandbox

Running your tests

By default phoenix apps should have an alias for mix run test that runs ecto.setup, ecto.migrate and test.

When pushing new commits to your repository, the workflow should trigger, do all kinds of magic and run this command for you.

You can find the full file in this gist: https://gist.github.com/Nickforall/e49f5f3c37414e05f9a6c604accf2c3e

If you have any questions feel free to hit me up on twitter

References

Use Github CI for Elixir Projects
https://help.github.com/en/articles/workflow-syntax-for-github-actions#jobsjob_idservices referenced August 29, 2019

7 ways to write logic with Elixir's pattern matching

Nick Vernij — Wed, 24 Apr 2019 09:17:06 +0000

I have started using Elixir a little less than a year ago, looking back at this year I have learned a lot about functional programming and Elixir in particular. We currently use Elixir in production, as a graphQL back-end, and it works like a charm.

The feature I love most is pattern matching, there are so many possibilities where I find ways to reduce the use of nested if-else blocks.

To quickly explain pattern matching, here is a little example:

# called with 1 apple
def say_apples(1), do: IO.puts("You have 1 apple")
# called with any other amount that 1
def say_apples(amount), do: IO.puts("You have " <> amount <> "apples")

By defining a literal as a function argument, we are matching against that literal. Meaning that when I call say_apples with a first argument of 1, it will execute the method has a matching 1 in its method definition.

Using an identifier, as you normally would when writing methods, will match with anything. Be aware that matching happens in the order you function are written in. When your first method definition matches with everything, any methods below will never be called.

So let's get to the point, here are 7 examples!

#1 "When" keyword

# true when the number is lower than 10
def lower_than_ten(number) when number < 10, do: true
# false when the number is higher than 10
def lower_than_ten(number), do: false

The when keyword can be used to execute expressions when matching, for example comparing the given argument.

#2 Matching struct types

# prints the name of the type
def print_type_name(%User{}), do: IO.puts("user")
def print_type_name(%Post{}), do: IO.puts("post")

While I won't go into the details of Elixir's type system, you'll want to match whether a struct is a certain type at some point.

#3 Extracting variables from structs

# says hi to our user
def say_hi(%User{name: name}) do
    IO.puts("Hiya, " <> name)
end

Structs are basically a key-value store, and sometimes you need one specific variable. I feel like in those cases, the above example reads way better than doing user.name in the method body.

#4 Pattern match of variable

# returns whether is_admin is true
def can_administer(%User{is_admin: true}), do: true
def can_administer(_), do: false

We can even pattern match on the value inside struct properties. Woah! Also notice how we use a _ if we don't really wanna use a variable but still want to match with everything.

I could just return is_admin, I know, but this is an example :)

#5 String concatenation

# returns true if a string starts with "foo"
def starts_with_foo("foo" <> _), do: true
def starts_with_foo(_), do: false

We can even use the concatenation operator in a method signature, to see if a string is prefixed with a certain string.

#6 First item in an array

# returns the first item in an array
def first([f | _]), do: f

first([1, 2, 3]) will return 1

#7 Everything but the first item in an array

# returns everything but the first item in an array
def tail([_ | t]), do: t

tail([1, 2, 3]) will return [2, 3]

The possibilities are endless! What are your favorite Elixir features?