DEV Community: Adz

Phoenix 1.7 for Elixir: Edit a Form in a Modal

Adz — Wed, 20 Sep 2023 14:11:58 +0000

In part one of this series, we introduced the CoreComponents that get generated when bootstrapping a new Phoenix project. In part two, we implemented a create modal.

Now, we will implement an edit modal.

You can continue following along with our companion repo.

Editing a Form in a Modal

You will first notice that each item will need a different changeset. We want to edit each item, so we need to be able to build a changeset from a different struct each time.

You could do this by iterating over all of the items in mount and rendering a different modal for every row, but this won't work at all. You would have to have one changeset per assign, which doesn't work when you have a list to add to. It would also mean a lot more HTML because you'd render the whole modal once per row. It's an all-round bad idea.

Instead, we need a way to build the correct changeset based on the item we click on. We can do that by using another JS function — push. This will push an event to the backend, along with any attributes that we want to send. If we add an edit button per row, the click action can push an event to the backend
with the pet_id as a param. Then, we can select the pet from the list of assigns and build a changeset out of it.

First, add the button to the markup. It might be nice to use an icon for this, so let's take a quick detour to icons.

Icons in Phoenix

Phoenix 1.7 ships with a vendored heroicons library and an <.icon> component in CoreComponents.
It works by supplying the name of an icon as a name attr, like so:

<.icon name="hero-cpu-chip" />

The names for the available icons are the filenames contained in the following path: assets/vendor/heroicons/optimized/20/solid/. Looking at the files doesn't tell us much about what they look like because we just see svg markup.

What would be cool is if we could render a dev-only route that displays all icons on one page. Then when we consider using an icon, we can go to that page and peruse them all at our leisure.

First, let's add the route:

# in lib/petacular_web/router.ex
live("/storybook", PetacularWeb.Pages.StoryBookLive, :show)

Then, we can make the necessary PetacularWeb.Pages.StoryBookLive module. We'll now write a function that generates all the icon names from the files in the assets folder, then iterate over them and create an icon from each one. This will give us a dynamic list of icons to render.

Here are the icon_names (this assumes you will start your server from the project's route):

# in lib/petacular_web/pages/story_book_live.ex

defp icon_names() do
  (File.cwd!() <> "/assets/vendor/heroicons/optimized/20/solid")
  |> Path.expand()
  |> File.ls!()
  |> Enum.map(fn path ->
    "hero-" <> String.replace(path, ".svg", "")
  end)
end

Then the markup:

# in lib/petacular_web/pages/story_book_live.ex
@impl true
def render(assigns) do
  ~H"""
  <div>
    <h1 class="text-xl mb-4 font-semibold">Storytime</h1>
    <div class="flex flex-col flex-wrap space-evenly">
      <%= for icon_name <- icon_names() do %>
        <section class="p-4 outline outline-1 mb-2 rounded">
          <h2 class="font-semibold"><%= icon_name %></h2>
          <div class="flex space-x-2 p-y-2 p-x-4 mr-2 my-2">
            <CoreComponents.icon name={icon_name} />
            <p>&ltCoreComponents.icon name="<%= icon_name %>"/&gt</p>
          </div>
          <div class="flex space-x-2 p-y-2 p-x-4 mr-2 my-2">
            <CoreComponents.icon name={icon_name<> "-mini"} />
            <p>&ltCoreComponents.icon name="<%= icon_name %>-mini"/&gt</p>
          </div>
          <div class="flex space-x-2 p-y-2 p-x-4 mr-2 my-2">
            <CoreComponents.icon name={icon_name<> "-solid"} />
            <p>&ltCoreComponents.icon name="<%= icon_name %>-solid"/&gt</p>
          </div>
        </section>
      <% end %>
    </div>
  </div>
  """
end

There is one more thing to do, though. Tailwind will purge all classes it doesn't see being used when the app is built. Usually, this is great because it means the bundle size is smaller, with more lightweight pages. However, here, it is going to bite us. When you refer to classes dynamically, Tailwind doesn't see those classes being used, so it purges them. Tailwind's docs warn about this.

We need to tell Tailwind not to purge all the icon modules so we can render them. We do that by adding a line of config into tailwind.config.js, like so:

safelist: [{ pattern: /hero\-.*/ }],

Now, we can head to http://localhost:4000/dev/storybook and see all the icons. See this commit for all of the changes.

Back to Editing Our Form

Okay, now we can select our edit icon and put it on the page.

<PetacularWeb.CoreComponents.icon name="hero-pencil-square-solid" class="mr-2" />

We will put this in a button and add a phx-click that opens our edit modal for us. All this can live in the homepage we used in parts one and two.

# in lib/petacular_web/pages/home_live.ex

  @impl true
  def render(assigns) do
    ~H"""
    ...

    <div class="w-50 mb-4">
      <%= for pet <- @pets do %>
        <div class="flex">
          <button phx-click={open_edit_modal(pet.id)}>
            <PetacularWeb.CoreComponents.icon name="hero-pencil-square-solid" class="mr-2" />
          </button>
          <p>Name: <span class="font-semibold"><%= pet.name %></span></p>
        </div>
      <% end %>
    </div>

    ...
    """
  end

We also need to create our Edit modal. This will be similar to our Create modal, but a bit different, so we'll just create a new modal.

We can put this in our ~H component just before the other modal:

# in lib/petacular_web/pages/home_live.ex

  @impl true
  def render(assigns) do
    ~H"""
  <PetacularWeb.CoreComponents.modal id="edit_modal">
    <h2>Edit a pet.</h2>

    <PetacularWeb.CoreComponents.simple_form for={@edit_changeset} phx-submit="edit_pet">
      <PetacularWeb.CoreComponents.input
        label="Name"
        id="edit_name"
        field={@edit_changeset[:name]}
        value={@edit_changeset[:name].value}
      />
      <:actions>
        <PetacularWeb.CoreComponents.button>
          Save
        </PetacularWeb.CoreComponents.button>
      </:actions>
    </PetacularWeb.CoreComponents.simple_form>
  </PetacularWeb.CoreComponents.modal>
    ...
    """
  end

Now we need to add a changeset to the assigns. Initially, we can put any changeset in mount because when we open the modal, we are going to seed it:

# in lib/petacular_web/pages/home_live.ex

@impl true
def mount(_params, _session, socket) do
  default_assigns = %{
    pets: Repo.all(Petacular.Pet),
    edit_form: Phoenix.Component.to_form(Petacular.Pet.create_changeset(%{})),
    create_form: Phoenix.Component.to_form(Petacular.Pet.create_changeset(%{}))
  }

  {:ok, assign(socket, default_assigns)}
end

Add the `open_edit_modal` Function

Now let's implement the open_edit_modal function. This has to do two things:

Open the modal.
Trigger a message to the backend so we can seed the changeset.

# in lib/petacular_web/pages/home_live.ex

defp open_edit_modal(pet_id) do
  %JS{}
  |> JS.push("open_edit_modal", value: %{pet_id: pet_id})
  |> PetacularWeb.CoreComponents.show_modal("edit_modal")
end

The handler for this event needs to select the relevant pet from the list of pets and put that into the changeset:

# in lib/petacular_web/pages/home_live.ex

@impl true
def handle_event("open_edit_modal", %{"pet_id" => id}, socket) do
  pet = Enum.find(socket.assigns.pets, &(&1.id == id))

  new_assigns = %{
    edit_form: Phoenix.Component.to_form(Petacular.Pet.edit_changeset(%{}, pet))
  }

  {:noreply, assign(socket, new_assigns)}
end

When we open the modal, the page will re-render the form because the changeset has changed, and the form will be seeded with the correct data. We can verify this by using
|> IO.inspect(limit: :infinity, label: "") on the form value:

value={@edit_changeset[:name].value |> IO.inspect(limit: :infinity, label: "edit for name:")}

Debugging an Issue with the `open_edit_modal`

If you open the modal, you will see the correct value printed. But there is a problem — it's not showing on the page! What on earth could be the issue? This one is a doozy, so I will save you some hours of debugging.

The function that we use to open our modal has this line, which focuses the first "focussable" element in the modal:

|> JS.focus_first(to: "##{id}-content")

This is done for accessibility, and so is generally a good idea.

The input happens to be the first focussable thing in our edit form. Phoenix also ensures that the client is the source of truth for an input's value:

For any given input with focus, LiveView will never overwrite the input's current value, even if it deviates from the server's rendered updates.

So what happens in our case? We push an asynchronous message to the backend, which changes an assign (the edit form), causing a re-render — |> JS.push("open_edit_modal", value: %{pet_id: pet_id}). Then we open the modal with JavaScript, but because the message to the server is async, the modal opens before we get a reply. The first focussable element is the input field, so that gets focus, then the server responds. This would normally re-render the input field, but now won't, because the input has focus!

Fixing the Issue

We've done everything right, yet are left adrift. What are our options?

Remove the auto-focus capabilities of the modal.
Have the edit modal focus on something that is not the input first.
Somehow make the form opening synchronous to the server message.

I honestly don't know which is better, but let's reason them out. One is easy to do — just remove this line from the show_modal function — but may have accessibility implications, which makes it a non-starter.

The second option seems reasonable at first. We could maybe set the tabindex on the heading, but mdn
recommends the following:

If an element can be focused using the keyboard, then it should be interactive; that is, the user should be able to do something to it and produce a change of some kind (for example, activating a link or changing an option).

So that's out.

The third option is possible, but requires some ceremony. Instead of opening the modal with JS, you could have the backend trigger a JS event that opens the modal when it's finished seeding the changeset. That requires adding a handler in JS to listen for the event and also means that the modal open is slower, because it requires at least one round trip to the server. For me, that is out as well.

The solution? A secret fourth option — set the value of the field with JS. This means the field will open quickly, be set to the correct value, and auto-focus.

To support that, we alter our open_edit_modal function to accept the name, then use JS.set_attribute to set the field value.

...
<button phx-click={open_edit_modal(pet.id, pet.name)}>
  <PetacularWeb.CoreComponents.icon name="hero-pencil-square-solid" class="mr-2" />
</button>
...

defp open_edit_modal(pet_id, pet_name) do
  %JS{}
  |> JS.push("open_edit_modal", value: %{pet_id: pet_id})
  |> JS.set_attribute({"value", pet_name}, to: "#edit_name")
  |> PetacularWeb.CoreComponents.show_modal("edit_modal")
end

Implementing the Update in Our Phoenix Application

Now the only thing left to do is implement the edit_pet handler. This is similar to the create version, where we flash an error and close the modal on success. We first want to select the pet we are editing, which means we need the pet's id. How can we get that?

The easiest way is to use a hidden input on the form. That way, when the form is submitted, the pet id will also be sent. To do that, we need to add the hidden input:

<%= Phoenix.HTML.Form.hidden_input(f, :id, id: "edit_pet_id_input") %>

And set the value when we open the modal:

defp open_edit_modal(pet_id, pet_name) do
  %JS{}
  |> JS.push("open_edit_modal", value: %{pet_id: pet_id})
  |> JS.set_attribute({"value", pet_name}, to: "#edit_name")
  |> JS.set_attribute({"value", pet_id}, to: "#edit_pet_id_input")
  # ^^^ this line ^^^^
  |> PetacularWeb.CoreComponents.show_modal("edit_modal")
end

We will see the id of the pet appear in the params, allowing us to select the pet we are editing from the assigns:

@impl true
def handle_event("edit_pet", %{"pet" => %{"id" => id} = params}, socket) do
  pet = Enum.find(socket.assigns.pets, &(&1.id == String.to_integer(id)))

  case Repo.insert(Petacular.Pet.edit_changeset(params, pet)) do
    {:error, message} ->
      {:noreply, socket |> put_flash(:error, inspect(message))}

    {:ok, _} ->
      new_assigns = %{
        pets: Repo.all(Petacular.Pet),
        edit_form: Phoenix.Component.to_form(Petacular.Pet.create_changeset(%{}))
      }

      socket =
        socket
        |> assign(new_assigns)
        |> push_event("close_modal", %{to: "#close_modal_btn_edit_modal"})

      {:noreply, socket}
  end
end

See this commit for all the relevant changes.

And with that, we are done!

Wrapping Up

This concludes our three-part series in which we took a fresh Phoenix 1.7 application and built a create and edit modal for
it.

Hopefully, this gives you some new ideas you can extend and implement for your own apps.

Happy coding!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

Add a Form to a Modal in Phoenix 1.7

Adz — Tue, 08 Aug 2023 13:35:19 +0000

In part one of this series, we introduced the core generated components when bootstrapping a new Phoenix project. We used a button and a modal from the core components to lay the groundwork for a "create modal".

In this post, we will put a form onto the modal and create pets.

Let's get started!

Note: As in the last post, you can follow along with our companion repo.

Adding a Form to Our Phoenix Application

There is a simple form included in PetacularWeb.CoreComponents. This expects two slots: an :inner_block, which will be our form input components, and :actions, which will be the submit buttons. The :actions slot is a named slot, meaning, we can render the components we want to use as buttons inside of an <:actions> tag, like this:

# in /lib/petacular_web/pages/home_live.ex

<PetacularWeb.CoreComponents.simple_form for={@create_form} phx-submit="create_pet">
  <:actions>
    <PetacularWeb.CoreComponents.button>
      Save
    </PetacularWeb.CoreComponents.button>
  </:actions>
</PetacularWeb.CoreComponents.simple_form>

The input components are also in PetacularWeb.CoreComponents and produce the correct kind of input based on the attrs used to define them. We just need a text field for now, so we can define the text input like so:

<PetacularWeb.CoreComponents.input field={@create_form[:name]} label="Name" />

If you don't define a type attr, it defaults to a text field. The @create_form is created from a changeset (as we will see in a moment).

Phoenix's Component `to_form`

Let's take a moment to talk about forms and changesets. We used to pass changesets directly to forms. But in Phoenix 1.7, a new to_form function generates a Phoenix.HTML.Form
struct from the given changeset.

This seemingly small change is a massive improvement, so it's worth talking about. First, it provides us with some indirection. Calling to_form ensures that what the <.form component sees is a Phoenix.HTML.Form struct, rather than a changeset. That means if we wanted to swap away from a changeset and use something else in the future (like a bare map of params), we could — with no changes to the <.form component itself. We just change the places we call to_form in mount and handle_event.

Next, the Phoenix.HTML.Form handles change tracking better. Up until Phoenix 1.7, if a form field changed, the whole form was re-rendered. Usually that's fine, but if you have a large complex form or dropdowns with lots of options, it can be a big boon not to have to re-render all of that each time you change a field.

Finally, it also simplifies the syntax. When we passed changesets through to forms, we used the :let attribute to assign the changeset to a variable we could refer to. Now we can omit that entirely. We can also refer to the value of a form field more simply; previously, you would have done something like: value={Ecto.Changeset.fetch_field!(@changeset, :my_field)}. With the form struct, it becomes: value={@form[:my_field].value}

A full before and after might look like this.

Before:

@impl true
def mount(_params, _session, socket) do
  default_assigns = %{
    changeset: Petacular.Pet.create_changeset(%{})
  }

  {:ok, assign(socket, default_assigns)}
end

~H"""
<.form :let={f} for={@changeset} phx-submit="...">
  <%= <Phoenix.HTML.Form.text_input(f, :my_field, value: Ecto.Changeset.fetch_field!(@changeset, :my_field)) %>
</.form>
"""

And after:

@impl true
def mount(_params, _session, socket) do
  default_assigns = %{
    create_form: Phoenix.Component.to_form(Petacular.Pet.create_changeset(%{}))
  }

  {:ok, assign(socket, default_assigns)}
end

~H"""
<.form for={@create_form} phx-submit="...">
  <input type="text" name={@create_form[:my_field]} value={@create_form[:my_field].value} />
</.form>
"""

Note how we don't need HTML.text_input anymore, and we don't have to reach into the changeset.

Check out the official Phoenix docs for more information.

Using `to_form`

First, set up a form in mount:

@impl true
def mount(_params, _session, socket) do
  default_assigns = %{
    create_form: Phoenix.Component.to_form(Petacular.Pet.create_changeset(%{}))
  }

  {:ok, assign(socket, default_assigns)}
end

Now we can build a form and use the pre-built inputs. These accept the field from the form (which is as easy as field={@create_form[:name]}).

<PetacularWeb.CoreComponents.modal id="create_modal">
  <h2>Add a pet.</h2>

  <PetacularWeb.CoreComponents.simple_form
    for={@create_form}
    phx-submit="create_pet"
  >
    <PetacularWeb.CoreComponents.input field={@create_form[:name]} label="Name" />
    <:actions>
      <PetacularWeb.CoreComponents.button>
        Save
      </PetacularWeb.CoreComponents.button>
    </:actions>
  </PetacularWeb.CoreComponents.simple_form>
</PetacularWeb.CoreComponents.modal>

Saving the Form

If we save and refresh the form, we should see that we can click a button and enter a name into it. The final thing to do to get this working is to write an event handler for the form submission.

Here is the first gotcha. We are using changesets to validate our forms. Because live views are stateful, we might be tempted to re-use the changeset in our assigns when we submit the form. This is not a good idea. What's worse, Ecto.Changeset.cast et al. will happily accept a changeset as input, meaning it's a very easy trap to fall into without realizing you are doing something wrong. The symptom might be errors in your changeset not disappearing as you expect, for example.

This trap is harder to fall into if you use to_form because the changeset is not in the assigns — the form struct is. This is another good reason to use to_form!

So every time we want to cast some params, we must create a fresh changeset. Let's do that:

# in lib/petacular_web/pages/home_live.ex
@impl true
def handle_event("create_pet", %{"pet" => params}, socket) do
  case Repo.insert(Petaclular.Pet.create_changeset(params)) do
    {:error, message} ->
      {:noreply, socket |> put_flash(:error, inspect(message))}

    {:ok, _} ->
      new_assigns = %{}
      {:noreply, assign(socket, new_assigns)}
  end
end

In the case of an error, we add a flash that shows it to the user, and when we successfully complete, we need to do two things:

Show the created pet.
Close the modal.

To show the new pet, we first need to render all pets on the page. So we will fetch them all from the DB in mount and then add some code to render them:

# in lib/petacular_web/pages/home_live.ex
@impl true
def mount(_params, _session, socket) do
  default_assigns = %{
    pets: Repo.all(Petacular.Pet),
    create_form: Phoenix.Component.to_form(Petacular.Pet.create_changeset(%{}))
  }

  {:ok, assign(socket, default_assigns)}
end

...

<h1 class="font-semibold text-3xl mb-4">Pets</h1>

<div class="w-50 mb-4">
  <%= for pet <- @pets do %>
    <p>Name: <span class="font-semibold"><%= pet.name %></span></p>
  <% end %>
</div>

Now that we can see them, we can refresh the list of pets when we add one successfully:

# in lib/petacular_web/pages/home_live.ex
@impl true
def handle_event("create_pet", %{"pet" => params}, socket) do
  case Repo.insert(Petacular.Pet.create_changeset(params)) do
    {:error, message} ->
      {:noreply, socket |> put_flash(:error, inspect(message))}

    {:ok, _} ->
      new_assigns = %{
        pets: Repo.all(Petacular.Pet)
      #  ^^^ add new
      }

      {:noreply, assign(socket, new_assigns)}
  end
end

This is great. If we try adding a pet, we will see the pet gets created and appears on the page, but the modal remains open.

Closing the Modal with `push_event`

Once we have successfully added a pet, we want to close the modal. There is already a "close the modal" button on the modal; the little X in the top right-hand corner. What if we could just target that?

Well, we can! There is a function called push_event that lets us emit a JS event from the backend. We can add some JavaScript that listens for that event and triggers a "click" event for the close button, effectively closing the modal.

First, we call push_event in the event handler:

# in lib/petacular_web/pages/home_live.ex
@impl true
def handle_event("create_pet", %{"pet" => params}, socket) do
  case Repo.insert(Petacular.Pet.create_changeset(params)) do
    {:error, message} ->
      {:noreply, socket |> put_flash(:error, inspect(message))}

    {:ok, _} ->
      new_assigns = %{
        pets: Repo.all(Petacular.Pet),
        create_form: Phoenix.Component.to_form(Petacular.Pet.create_changeset(%{}))
        # reset the form back to being empty ^^^
      }

      socket =
        socket
        |> assign(new_assigns)
        |> push_event("close_modal", %{to: "#close_modal_btn_create_modal"})
        #  ^^^^ add this
      {:noreply, socket}
  end
end

Now to react to the event, we have two options:

Add a global event listener for the event.
Use a hook.

Let's try the second approach. First, we'll wire up the hook in app.js:

const ModalCloser = {
  mounted() {
    this.handleEvent("close_modal", () => {
      this.el.dispatchEvent(new Event("click", { bubbles: true }));
    });
  },
};

let liveSocket = new LiveSocket("/live", Socket, {
  params: {
    _csrf_token: csrfToken,
  },
  hooks: {
    ModalCloser: ModalCloser,
  },
});

Now let's put the hook onto the close modal button in PetacularWeb.CoreComponents (remember, anything that has a hook also needs an ID). To help us later cater for multiple modals on one page, let's use the required @id attr as part of the id:

<button
  id={"close_modal_btn_" <> @id}
  phx-hook="ModalCloser"
  <!-- ^^ Add these ^^ -->
  phx-click={JS.exec("data-cancel", to: "##{@id}")}
  type="button"
  class="-m-3 flex-none p-3 opacity-20 hover:opacity-40"
  aria-label={gettext("close")}
>
  <.icon name="hero-x-mark-solid" class="h-5 w-5" />
</button>

You can see all the changes in this commit. Fantastic, we now have a working create modal! 🎉

Wrapping Up

In the second part of this series, we successfully added a form to the modal that creates new pets.

Stay tuned for the third and final part, where we will edit an existing pet.

Until then, happy coding!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

Create and Open a Modal in Phoenix 1.7

Adz — Tue, 27 Jun 2023 11:00:00 +0000

Phoenix 1.7 came out this year with a whole host of exciting features, including verified routes and some great built-in Tailwind components. These components are a fantastic start, but they are not made to be a fully general design system. We should expect to modify components to fit our specific needs. However, knowing where to start can be difficult.

In this three-part series, we'll take a fresh Phoenix app and create a working UI using generated components.

In this part, we will add a modal to a page and open it on demand.

Let's get started!

The UI of Our Phoenix App — Setup

The UI we will implement is a list of data and two modals for that data: a create modal and an edit modal. Our example will be a spectacular pet shop called Petacular.

To begin, let's bootstrap the app. If you wish to write the command yourself, first ensure you have the latest Phoenix installer with:

mix archive.install hex phx_new

Then run:

mix phx.new petacular

This will bootstrap the project and generate the core components we'll use in our examples. To illustrate the various steps in this article, I have included a companion repo with commits for each step. This commit shows us everything that gets generated in the above command. Of particular interest is this module which contains all of the generated components we will be exploring.

The components use Tailwind CSS for styling and are passed attributes and/or slots, as appropriate. We will leverage a few below, but first, we will need a database.

Check out this commit for everything we need to get a db working with docker. This commit adds a migration and creates a few schemas we will use for our example: a list of pets and their preferences. Finally, you can see how this commit makes the home page a LiveView page and introduces some very basic styling.

What Is a Modal in Phoenix?

The initial homepage looks like this (found in lib/petacular_web/pages/home_live.ex):

@impl true
def render(assigns) do
  ~H"""
  <h1 class="font-semibold text-3xl mb-4">Pets</h1>
  <PetacularWeb.CoreComponents.button>
    Add New Pet +
  </PetacularWeb.CoreComponents.button>
  """
end

I have included a built-in component from the generated PetacularWeb.CoreComponents module (found in lib/petacular_web/components/core_components.ex) — a button. The button is defined here and it is simple to use:

# in /lib/petacular_web/pages/home_live.ex
...
~H"""
    <PetacularWeb.CoreComponents.button>
      Add New Pet +
    </PetacularWeb.CoreComponents.button>
"""
...

We would love for this to open a modal that contains a form for adding a pet. To do that, let's look at the modal in the PetacularWeb.CoreComponents module.

This is a function component, meaning it does not have a state. It's just a bundle of markup and styling. It has some attrs — for example, attr :show, :boolean, default: false, and one slot.

What Are `attr`s and Slots?

An attr defines data that's expected to pass. Some attrs are required, and some have a default value instead. A slot is space for nested HTML and can be named or not. In essence, slots let you provide your own markup and appear as children of a function component's element.

We can see the slot is called :inner_block, a special name for the modal. Everything inside of the <.modal> tags will be treated as the :inner_block slot. So, in the function docs, the modal component looks like this:

<.modal id="confirm-modal">
  This is a modal.
</.modal>

The text This is a modal. is treated as the :inner_block. In contrast, we can name a slot. Then we designate the contents of that slot by putting content in between two tags that use the slot's name. For example, CoreComponents has a <.header> component with an optional :subtitle slot. To provide a subtitle, we do this:

<CoreComponents.header>
  This is my title.
  <:subtitle>
    This is my subtitle. There are many like it but this one is mine.
  </:subtitle>
</CoreComponents.header>

Making the Modal Appear in Phoenix

The docs for the modal give us an indication of what the modal needs to look for. We need to provide an ID that is targeted by the hide_modal and show_modal functions. Let's look at how they work first. The show modal is defined like this:

# in lib/petacular_web/components/core_components.ex

def show_modal(js \\ %JS{}, id) when is_binary(id) do
  js
  |> JS.show(to: "##{id}")
  |> JS.show(
    to: "##{id}-bg",
    transition: {"transition-all transform ease-out duration-300", "opacity-0", "opacity-100"}
  )
  |> show("##{id}-container")
  |> JS.add_class("overflow-hidden", to: "body")
  |> JS.focus_first(to: "##{id}-content")
end

def show(js \\ %JS{}, selector) do
  JS.show(js,
    to: selector,
    transition:
      {"transition-all transform ease-out duration-300",
       "opacity-0 translate-y-4 sm:translate-y-0 sm:scale-95",
       "opacity-100 translate-y-0 sm:scale-100"}
  )
end

This uses the new(ish) JS module to execute simple JavaScript functions. It accepts and uses an ID to identify the element we want to show. Upon appearing, the show modal does some simple animations to ease it into view and focuses the page onto the first focus-able element, if there is one.

hide_modal does the same, but in reverse:

# in lib/petacular_web/components/core_components.ex

def hide_modal(js \\ %JS{}, id) do
  js
  |> JS.hide(
    to: "##{id}-bg",
    transition: {"transition-all transform ease-in duration-200", "opacity-100", "opacity-0"}
  )
  |> hide("##{id}-container")
  |> JS.hide(to: "##{id}", transition: {"block", "block", "hidden"})
  |> JS.remove_class("overflow-hidden", to: "body")
  |> JS.pop_focus()
end

def hide(js \\ %JS{}, selector) do
  JS.hide(js,
    to: selector,
    time: 200,
    transition:
      {"transition-all transform ease-in duration-200",
       "opacity-100 translate-y-0 sm:scale-100",
       "opacity-0 translate-y-4 sm:translate-y-0 sm:scale-95"}
  )
end

Calling the `show_modal` Function

With a button click, we call the show_modal function to make the modal appear. To close the modal, we need a button on the modal itself that calls hide_modal. Luckily, this is implemented for us, so we don't need to worry about it.

From our function docs, we see that we need some content inside the modal. Like the button we used earlier, the modal uses an :inner_block slot. That means anything inside the modal tags will appear on the page as the :inner_block. We can keep this very simple. Something like the following will work for now:

# in /lib/petacular_web/pages/home_live.ex

<PetacularWeb.CoreComponents.modal id="create_modal">
  <h2>Add a pet.</h2>
</PetacularWeb.CoreComponents.modal>

We can put this inside our homepage and have a click trigger the show_modal function by adding phx-click onto the button we used earlier. Usually, we set phx-click to a string, and clicking it sends an event to the backend using that string as the event name. But we may also provide a JS function or a chain of them:

# in /lib/petacular_web/pages/home_live.ex

<PetacularWeb.CoreComponents.button phx-click={
  PetacularWeb.CoreComponents.show_modal("create_modal")
}>
  Add New Pet +
</PetacularWeb.CoreComponents.button>

Putting it all together, we end up with something like this:

# in /lib/petacular_web/pages/home_live.ex

~H"""
  <h1 class="font-semibold text-3xl mb-4">Pets</h1>

  <PetacularWeb.CoreComponents.modal id="create_modal">
    <h2>Add a pet.</h2>
  </PetacularWeb.CoreComponents.modal>

  <PetacularWeb.CoreComponents.button phx-click={
    PetacularWeb.CoreComponents.show_modal("create_modal")
  }>
    Add New Pet +
  </PetacularWeb.CoreComponents.button>
"""

Now when you click the button, the modal will open! 🎉

See the full diff of changes.

Wrapping Up

In this post, we used Phoenix 1.7's generated core components to create a modal and open it.

In part two, we'll add the edit form.

Until then, happy coding!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

Faster XML Parsing with Elixir

Adz — Tue, 11 Oct 2022 11:34:16 +0000

The XML data format has been around since 1996. It was first envisioned as a lingua franca (bridging language) for data to be serialized and read into completely disparate systems (with different programming languages, operating systems, and even hardware). It has been wildly successful in that goal.

In software, though, 26 years is like a lifetime — and in hardware, it's an eternity. So much has changed in that short time that it's easy to forget just how different the world was when the standard was proposed.

That brings us to the topic of today's post. How can we parse XML quickly and efficiently? What does state-of-the-art XML parsing look like?

Let's get going!

XML Parsing with Elixir — An Introduction

As much as we may want to criticize XML (and there is plenty to criticize), we have to put it in its historical context. Anything that survives that long has clearly found some utility!

Thinking critically about XML as a format is great if you are in a position to change or improve it, or when deciding whether you should use it.

But for most, the choice is already made for us. The entire airline industry and much of finance run on XML — so if you work in those industries, you will likely need to parse it.

We will define parsing in this post as doing two things:

Verifying a document is valid (i.e., that it is actually XML).
Extracting values from that valid document.

A valid document is not much use if we can't access the values in our program's XML. We will also specifically talk about XML documents where we know the expected shape of the XML ahead of time.

We'll provide an overview of some possibilities when parsing XML, including actual numbers from real-world applications.

Three Approaches to XML Parsing with Elixir

There are three broad approaches we will talk about:

Building a DOM
Virtual Token Descriptor (VTD)
Simple API for XML (SAX) parsing

Building a DOM

Building a DOM from XML is probably the most common way to think about XML parsing. It's what browsers do with HTML, and it preserves the tree structure that can make thinking about and validating an XML document much easier.

DOM stands for Document Object Model — but it really means a structured representation of XML in your given language. Elixir doesn't have Objects, but we can still have a DOM.

There are lots of mature tools in this area. Erlang even comes with a built-in data structure for representing an XML document called xmerl.

Xmerl represents XML so that XPath queries are possible, and an XPath query engine is also built into Erlang. What is XPath? It is to XML what SQL is to a database — a query language for accessing the data inside it.

For example, here is an XPath query to get the text from the XML snippet below: /Author/text()

<Author>James Eagan</Author>

You can use built-in functions to access the text in the tags:

xml = "<Author>James Eagan</Author>"
# First build the xmerl:
{xmerl, _} = xml |> :erlang.binary_to_list |> :xmerl_scan.string()

# Now we can apply the xpath.
:xmerl_xpath.string('/Author/text()', xmerl)

This tooling maturity can be a fast way to get up and running. There is a chance your team knows of XPath from other languages, which makes extracting data a breeze, and using the built-in xmerl format means 0 extra dependencies.

But there is a problem. Resources! With large XML files creating an xmerl, DOM can really balloon memory requirements. It can become prohibitively expensive in terms of latency and memory. Here is a Benchee output excerpt of a ~9mb XML file that uses xmerl and XPath:

Benchmarking xmerl with querying ...

Name                                   ips        average  deviation         median         99th %
...
xmerl with querying                 0.0809        12.36 s     ±1.98%        12.42 s        12.59 s

Comparison:
...
xmerl with querying                 0.0809 - 12.68x slower +11.39 s

Memory usage statistics:

Name                            Memory usage
...
xmerl with querying               2340.31 MB - 10.22x memory usage +2111.41 MB

That's a lot of megabytes! And as the output indicates, we can do much better.

Virtual Token Descriptor (VTD) in Elixir

VTD stands for Virtual Token Descriptor. A VTD is a completely different way to think about parsing XML. Instead of building a DOM, the idea is to tokenize the XML document and store the locations of key bits of information inside it.

In Elixir, this could mean storing the start index and length of all the nodes and attrs in the XML. You then use binary_part
to access any given location (in constant time!) and extract values when needed.

We leave the original XML binary untouched in a VTD approach (unlike a DOM, where we manipulate the original XML binary). Instead, in a VTD we build up all the information we need to query the original binary.

VTD to XML Parsing: An Example

Let's imagine a simplified example. This is not how VTD works exactly, but it will give you a sense of what it does without getting bogged down in edge cases.

Given this XML:

<Author age="22">Seth Milchick</Author>

Let's imagine the information we want to be able to retrieve is:

Node name — "Author"
age attribute — "22"
<Author>'s text content

To do that, we could build a table that looks like this:

xml = "<Author age=\"22\">Seth Milchick</Author>"

table = [
  {:node, 1, 5},
  {:attribute, 8, 3},
  {:attribute_value, 13, 2},
  {:text, 17, 13},
]

The tuple denotes what we are pointing at, e.g., :node, then provides the start index for that element. The last number in the tuple is how long the element is.

If we look to get the XPath /Author/text(), we can access that table and see if the root node matches "Author", something like:

node_in_table? = Enum.any?(table, fn
  {:node, start, length} -> binary_part(xml, start, length) == "Author"
  _ -> false
end)

if node_in_table? do
  case Enum.find(table, &match?({:attribute_value, _, _}, &1)) do
    nil -> :not_text
    {:attribute_value, start, length} -> binary_part(xml, start, length)
  end
else
  :not_found
end

As you can see, how we represent that table is very important. This is the secret sauce of VTD. If we were inefficient, we could end up with a table the same size (or larger!) than a DOM. Or we could take a long time to find the element we care about in the table, eliminating any potential performance gains from binary_part.

An actual VTD table stores references to child and sibling nodes in a way that makes randomly accessing a given element as good as in a DOM. However, because we don't chop up the original binary into its own objects, the memory requirements can be vastly lower. The creators claim that the table's size can only be 1.5 times the size of the XML document. Lower memory requirements also mean it can be fast.

In fact, the parsing method was designed for on-chip implementations. This 'XML on a Chip?' document describes how you can use custom hardware to blaze through XML!

What's more, existing VTD implementations all support the full XPath feature set. That means it is (in theory) possible to have custom hardware churn through XML parsing without incurring a massive cost in developer complexity. I say 'in theory' because you first have to create the custom hardware, and then execute it with a suitably low-level language.

In fact, there are currently no Elixir libraries for VTD. I know of two libraries being worked on (one in Erlang and one in Elixir) as part-time open source projects, as of yet unfinished and unreleased. Perhaps you can take inspiration from other languages and have a go at porting it.

As cool and interesting as this approach sounds, though, there are more trade-offs.

Trade-offs of VTD

While XPath is probably familiar to some, it...isn't great. When a node in a path doesn't exist, you just get nil or an empty string back. This is a pain because you are never sure if you mistyped the path or if the value actually isn't there. Verifying that can be manual and annoying. XPath functions also don't tell you which node doesn't exist, making debugging harder. Having XPath as the primary way you extract data from an XML document can prove quite painful.

Additionally, VTD requires an entire document to exist in memory first, unlike sax parsing (as we will see). This could make parsing a stream of XML with VTD difficult.

Finally, there is a minimum amount of data that we need to extract from an XML document. We need to turn that data into useful things (like an Elixir Date struct) and those Elixir data structures are of a certain size. If they amount to more in memory than the parsing takes, we don't gain anything from further reducing the memory footprint of the parsing. In some situations, the impressive memory savings don't translate to an actual saving in our programs (because as soon as you transform the parsed data into structured data, the memory jumps up again anyway).

So, let's look at our final approach — sax parsing.

SAX Parsing in Elixir

A SAX (Simple API for XML) parser works by iterating through a document and emitting events when certain things happen. For example, the Saxy parser emits the following events.

:start_document
:start_element
:characters
:cdata
:end_element
:end_document

When Saxy sees the start of a tag, for example, it gets its name and attributes and calls a callback you can implement. You can do whatever you like with that information.

The specific events available vary by implementation. Erlang has a built-in SAX xmerl parser that offers extra events like :comment and :ignorableWhitespace.

The emission of events is usually very fast. In Elixir, we can use binary pattern matching to great effect; Saxy will iterate through a document and use pattern matching to extract node names and attributes. But this only achieves half of what you actually need. You then have to identify when a value is one you care about, which is not as simple as it sounds.

SAX Parsing: An Example

Let's imagine you want to access the text inside the <Name> tag below:

<Author>
  <Name>Nick Riviera</Name>
</Author>

For this simple case, you first need to wait for the :start_element event where the node_name is Name:

def handle_event(:start_element, {"Name", attrs}, state) do
  # In here we know we have just opened the Name tag.
end

# This case is for any other tag that we open.
def handle_event(:start_element, {_, _attrs}, state) do
 {:ok, state}
end

But the :characters event is separate, meaning we have to put something into the state to let us know which tag's characters we're seeing:

def handle_event(:start_element, {"Name", attrs}, state) do
  # In here we know we have just opened the Name tag, so let's just put that in state.
  {:ok, [{"Name", attrs} | state]}
end

def handle_event(:start_element, {_, _attrs}, state) do
 {:ok, state}
end

Now, when we get the :characters event, we can check the state and see if we are "inside" the tag we care about:

# If "state" is the name tag we know it's the text we care about.
def handle_event(:characters, text, [{"Name", _} | rest]) do
  # Now we can do something with the text since we know it will be the text of <Name>.
  # ...
end

def handle_event(:characters, _, state) do
 {:ok, state}
end

That works great, but now consider this XML:

<Blog>
  <Name>XML Parsing</Name>
  <Author>
    <Name>Nick Riviera</Name>
  </Author>
</Blog>

Our approach will break here because we need to know which <Name> node we have encountered.

The solution is to use a stack. Each time we open a tag, we add that element to the stack, and when we close an element, we can discard it.

Trade-offs of a Stack

Changing our mindset to think in stacks is not simple, especially when we normally think in recursion.

It also makes validating the XML more complicated. If you don't get the value that you expect, it can be difficult to figure out what went wrong and when. You can print the stack, but figuring out how it got to be like that basically requires implementing your own stack tracing algorithm. So debugging is not trivial.

Implementing the callbacks for each XML document you want to parse can be an awful lot of work. It is difficult to re-use shared code across handlers because each time you accumulate different state. You might want to create an %Author{} struct for this:

<Author>
  <Name>Nick Riviera</Name>
</Author>

But for this document:

<Flight departureTime="1pm" />

You might want a %Flight{} struct.

The only generic functionality is to manage the stack as you progress through a document. However, the specific elements and what you want to pull out of a document and put into the state you accumulate will be different. You really have only two options:

Write a unique handler per document that accumulates all the data you want to pull from the XML document.
Have a generic handler used by every document, which puts everything into a generic XML data structure.

Number 1 allows you to collect only the data you wish to pull from the XML and ignore the rest but it requires writing a custom handler for each XML document.

And number 2 — well, number 2 is a DOM 😅.

By default, Saxy actually does number 2 — it creates a data structure called SimpleForm, a tuple DOM that looks like this:

{node_name, attributes, children}

Where children is a list of more tuple nodes or text — for example:

<Blog>
  <Name>XML Parsing</Name>
  <Author>
    <Name>Nick Riviera</Name>
  </Author>
</Blog>

Becomes:

{"Blog", [], [
  {"Name", [], ["XML Parsing"]},
  {"Author", [], [
    {"Name", [], ["Nick Riviera"]}
  ]}
]}

Great...but haven't we just run slap-bang into all of the DOM problems we mentioned above? Well, almost. We are in full control of the created DOM, which means we can be clever.

The xmerl DOM we mentioned before is designed to enable XPath, but if we can live without that (and I maintain that we can, nay, we can improve on it), we can significantly reduce the size of the DOM we create.

We need to be willing to do two things:

Replace XPath with something.
Design a more minimal DOM.

I have seen amazing improvements over xmerl doing just this; an order of magnitude less memory and a latency improvement of the same.

For 2, we can go with SimpleForm for now, but let's look at what we can do about 1.

Querying the DOM with DataSchema

While a custom query engine may sound scary, it's an opportunity to improve.

Opting to navigate a DOM in Elixir means we don't have a black box XPath implementation that just returns nil when it's not happy (leaving you to figure out if the data wasn't there or if you just typed the path wrong).

Usually, everything we ever need from the XML boils down to one of three things:

A node
A node's text
A node's attr

We either want one, or many, of each of these things. We end up with an API that's something like:

get_text
get_attr
get_all_attrs
get_all_text
get_node
get_all_nodes

How DataSchema Works

To help improve the developer experience even further, I wrote DataSchema. DataSchema is like Ecto's embedded schemas but generalized to any input type, including XML.

It allows us to write declarative schemas that describe structs we can create from input data. For example, this is a schema for the XML snippet above:

<Blog>
  <Name>XML Parsing</Name>
  <Author>
    <Name>Nick Riviera</Name>
  </Author>
</Blog>

defmodule Blog do
  import DataSchema, only: [data_schema: 1]

  @data_accessor SimpleFormAccessor
  data_schema(
    field: {:title, ["Blog", "Name", "text()"], StringType},
    field: {:author_name, ["Blog", "Author", "Name", "text()"], StringType},
  )
end

There are some really good livebooks
in the repo to learn the library properly, but let's break down the basics of the schema.

Each field in a schema defines a key in a struct. You can see the key below:

field: {:title, ["Blog","Name","text()"], StringType},
 #      ^^^^^^^
 #  The struct key

The next element in that tuple is a path to a piece of data in the XML:

field: {:title, ["Blog","Name","text()"], StringType},
 #                   ^^^^^^^
 #               Path to a value

We are in full control of what that path can look like, but for now, I've opted to make it a list of XML nodes that mirror what an XPath query would look like split on "/".

The last element in that tuple is a casting function. When we call:

DataSchema.to_struct(xml, Blog)

DataSchema will get the value at the end of the path (for each field) and pass it to a casting function. This gives us a chance to alter it in some way.

field: {:title, ["Blog","Name","text()"], StringType},
 #                                         ^^^^^^^
 #                                    casting function

The casting function can be a module that implements a cast/1 function, an anonymous fn, or a Mod Fun Args tuple.

Finally, DataSchema needs to apply the path to the input data
it transforms.

We provide a @data_accessor in the schema:

...
@data_accessor SimpleFormAccessor
#                 ^^^^^^^^^
#              Accessor module
...

This module will implement a callback that gets passed the path and the input data (in our case, XML). The return value of that function is given to the casting function.

This accessor is where we can implement the traversal of the SimpleForm data structure. This is relatively easy. Here is an example snippet getting the text of an element:

def get_text(["text()"], {_, _, children}) do
  Enum.filter(children, &is_binary/1)
end

def get_text([node_name | rest], {node_name, _, children}) do
  get_text(rest, children)
end

def get_text([node_name | _], _) do
  {:error, "node not found #{node_name}"}
end

This small snippet demonstrates the improvement we can get over XPath because we can now log out the exact node that we could not find. This is a huge developer experience productivity boost.

All this comes together so that when we call DataSchema.to_struct(xml, Blog), it returns:

{:ok, %Blog{title: "XML Parsing", author_name: "Nick Riviera" }}

This is the flow of data:

XML binary =>
  Saxy (to create a SimpleForm DOM) =>
    Query that DOM with DataSchema =>
      Struct

XML Parsing with Elixir: Taking it One Step Further

In the wild, I've found that the Saxy/DataSchema approach improves over the xmerl DOM by order of magnitude. But we can go one step further.

Our schemas are declarative specifications of all the data we want from the XML. We can feed this information into a saxy handler and only include elements in the DOM that our schema needs.

This nifty trick works out especially well for schemas where you only need a small amount of the data in the XML document. If the data you end up with is larger in memory than the DOM you build, you don't need to worry about making the DOM smaller. But if it isn't, then building the DOM can cause waste and garbage, as you end up ignoring most of it.

We need to transform our schema into a tree with the schema's paths — e.g., for this Blog schema:

defmodule Author do
  import DataSchema, only: [data_schema: 1]

  @data_accessor SimpleFormAccessor
  data_schema(
    field: {:name, ["Author", "text()"], StringType},
  )
end

defmodule Blog do
  import DataSchema, only: [data_schema: 1]

  @data_accessor SimpleFormAccessor
  data_schema(
    field: {:title, ["Blog", "Name", "text()"], StringType},
    has_one: {:author, ["Blog", "Author"], StringType},
  )
end

We would create a tree of paths that looks something like:

%{
  "Blog" => %{
    "text()" => true,
    "Author" => %{
      "text()" => true
    }
  }
}

Handing that tree to the Saxy handler allows us to skip entire sub-trees of the XML.

To demonstrate this, let's parse the XML with the above schema.

<Blog>
  <Comments>
    <Comment>Superb!</Comment>
    <Comment>Amazing!</Comment>
  </Comments>
  <Name>XML Parsing</Name>
  <Author>
    <Name>Nick Riviera</Name>
  </Author>
</Blog>

First, recall that the key to parsing in this manner is to create a stack of elements. As you can see, when we build a SimpleForm DOM, we maintain a stack of nodes. When we get a :start_element event, we put that element onto the top of the stack.

When we receive an :end_element event, we put the element that is on the top of the stack into the children of the element below it (its parent).

But this time our handler has a schema and therefore a record of the values we actually care about. We can now query it every time we start a new element and ask "is this element in the schema?". If it is, we do as explained above and add it to the stack. If it isn't, we add a special node to the stack:

{:skip, 1, tag_name}

When we close a tag that we are skipping (i.e. when the top of the stack is that tuple) then we just pop that {:skip, 1, tag_name} element off of the stack and discard it. But the real win is if we open another tag before that one closes — i.e. when we meet the child of a skipped element.

In the example above, it would go like this:

We open <Comments> and see it is not in the schema, so we add :skip.
We get an event for the start of the <Comment> tag. We see that the top of the stack is a :skip element, so we immediately return:

def handle_event(:start_element, _element, [{:skip, _, _} | _] = stack) do
  {:ok, state}
end

This continues until we close <Comments> and the :skip element is removed. Then we continue as normal.

Okay, but what is that 1 doing in the middle? This is effectively a reference count.

Consider this XML:

<Blog>
  <Comments>
    <Comments>
    </Comments>
  </Comments>
</Blog>

While nasty, it's perfectly valid XML that risks the following:

We add a :skip tag for the opening of the first <Comments>.
The opening of the second <Comments> is skipped.
On the closing of the second <Comments>, the name of the "skipped" tag matches this one, so we remove the skipped element from the stack, even though we haven't actually finished skipping yet.

One solution to this is to add a :skip tag for every element you want to skip. But then you don't save any memory, as you still end up with a stack of every element — you just remove it more quickly. The memory will seem lower but will spike high during parsing.

Instead, we'll keep a count of elements with the same name as the skipped element once we start skipping. Then, each time we close one of those elements, we decrement the count. If it's ever 0, we are done skipping and can remove the tag.

This approach speeds up the latency of parsing a little, but importantly (along with some other tricks) massively trims down the size of the SimpleForm DOM that gets created.

See a version of the full Saxy handler.

There is even more we could do in this vein. For example, this approach stores all nodes along the path to the value we want. But if we just want the value at the end of the path, could we keep that value and none of the intermediary nodes? This comes with its own problems. We'll leave discovering these problems as an exercise for you 🙂.

Wrap Up

This concludes our tour of some interesting ways to parse XML faster, including building a DOM, using a VTD, and SAX parsing. We also went one step further, feeding data into a
Saxy handler (including elements in the DOM needed by our schema).

My hope is to one day open source a complete implementation of the slimmed down Sax parser, but for now, I hope this post has stimulated some of your own ideas.

Happy coding!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

Livebook for Elixir: Just What the Docs Ordered

Adz — Tue, 31 May 2022 10:48:03 +0000

While initially conceived as a tool for data exploration (much like Jupyter for Python), Livebook has deservedly become a sensation in the Elixir community.

It has been fantastic to see all the wonderful ways teams are leveraging Livebook for a range of different use cases. We have seen Livebooks being used to:

Create interactive documentation for libraries.
Build onboarding material and guides.
Audit and explore potential dependencies in your app.

Livebooks have also been used as the default REPL interface for project development.

In this post, we'll show how you can easily create interactive documentation with Livebook and outline some top tips for using Livebook. We will assume you have installed Livebook, following the guidance in their README.

But First: What is Livebook for Elixir?

Livebooks are supercharged markdown files where you can add sections of arbitrary executable Elixir code. They are inspired by similar notebooks for other languages (like Python's Jupyter), but Livebooks leverage LiveView and other BEAM goodies, so they are even better.

Livebook files get their own .livemd extension, and (somewhat confusingly) we create and run those Livebook markdown files using a Phoenix application also called Livebook.

That phoenix app runs in the browser and enables a whole host of interactive features like collaboration, as we will see.

The expectation is that you will install the Livebook repo locally and start a Livebook server from somewhere on your machine where there are Livebooks (the files).

The Livebook app will show you the working directory of where you started the Livebook server, so you can select any given Livebook to run from there.

Let's now look at a library to document.

Livebook Docs: A Single Source of Truth in Elixir

Our library is going to accept various inputs and rate them according to the following chonk chart:

It will output the chonk rating accordingly. First, let's create the library.

mix new chonk_o_meter && cd chonk_o_meter

Let's add ex_doc to our deps in our mix.exs:

defp deps do
  [
    {:ex_doc, ">= 0.0.0", runtime: false, only: [:docs, :dev]},
  ]
end

Now, download the chonk chart image above and put it into the root of the library in a directory called images so we can refer to it in our README. In the README.md, let's put a title and a short explanation of what the library aims to do:

# Chonk 'O' Meter

Chonk O Meter is a state-of-the-art size estimator. It will rate the size of anything according to the following chart:

![alt chart showing cats of various sizes](./images/chonk.jpg)

So far, so good. Now we will open the module and write our moduledoc. But here's the thing: what we really want to do is just copy what we already wrote for the README.

Having one source of truth for that information is super valuable as the library develops because having to update the documentation in multiple places is a recipe for errors!

It's good to repeat the same information in different formats because different people will come to the library via different paths.

Some may see the repo first (and therefore the README), whereas others may see the library on Hex first — and so only see the moduledoc.

You may think that it's easy enough to copy and paste, but once we add our Livebook into the mix, there will be three places we need to update docs when something changes!

Instead, let's be a bit smarter. We will section off a part of the README and read that section into the moduledoc at compile time. Sandwich the introduction to the library between two markdown comments in the README:

<!-- README START -->

.... Library introduction here.

<!-- README END -->

Now, we can write the introduction as if it were a moduledoc in between those two comments, like so:

<!-- README START -->

Chonk O Meter is a state-of-the-art size estimator. It will rate the size of anything according to the following chart:

![alt chart showing cats of various sizes](./images/chonk.jpg)

<!-- README END -->

In the main module ChonkOMeter, we can do this:

defmodule ChonkOMeter do
  @moduledoc File.read!(Path.expand("./README.md"))
             |> String.split("<!-- README START -->")
             |> Enum.at(1)
             |> String.split("<!-- README END -->")
             |> List.first()
end

This will extract the guide sandwiched between the markdown comments and set it as the moduledoc. Now we only need to change the README to update both!

We can generate the documentation and view it locally to verify that this works as expected. If you run mix docs, a doc folder will appear with an index.html file. We can open doc/index.html to view our documentation in the browser.

Adding an Image to the Moduledoc

If you navigate to the module's documentation, you will notice that the image is missing. Hex allows you to point to assets in your docs as long as they are included inside the doc directory (generated when you create docs with the mix docs command).

Usually, that command overwrites the whole doc folder. So, to ensure that our pictures are always copied there, we can use an alias in our mix.exs file. We will turn the mix docs command into one that runs mix docs and then copies all images inside the /images directory into a doc/images directory.

defmodule ChonkOMeter.MixProject do
  use Mix.Project

  def project do
    [
      ...
      aliases: aliases(),
      ...
    ]
  end

  defp aliases() do
    [docs: ["docs", &copy_pictures/1]]
  end

  defp copy_pictures(_) do
    File.cp_r(Path.expand("./images/"), Path.expand("./doc/images/"))
  end
end

If you run mix docs now, you will see that the images/ directory gets copied over to the doc folder. Open the doc/index.html file and you should now see the chonk chart appear!

Doctests in Elixir's Livebook

It's important to note that in writing our moduledoc in this way, we don't lose any of the usual capabilities ex_docs give us.

Anything you can normally do in a doctest, you can still do here. To demonstrate that, let's add a doctest to our README. First, we'll need a function to test:

defmodule ChonkOMeter do
  @moduledoc File.read!(Path.expand("./README.md"))
             |> String.split("<!-- README START -->")
             |> Enum.at(1)
             |> String.split("<!-- README END -->")

  @doc """
  Returns the Chonk rating for a given number of story points.
  """
  def story_points(points) when is_integer(points) and points >= 0 and points < 3 do
    "A Fine Boi"
  end

  def story_points(points) when is_integer(points) and points >= 3 and points < 5 do
    "He Chomnk"
  end

  def story_points(points) when is_integer(points) and points >= 5 and points < 8 do
    "A Heckin' Chonker"
  end

  def story_points(points) when is_integer(points) and points >= 8 and points < 10 do
    "H E F T Y C H O N K"
  end

  def story_points(points) when is_integer(points) and points >= 10 and points < 15 do
    "Mega Chonk"
  end

  def story_points(points) when is_integer(points) and points >= 15 do
    "Oh Lawd He Comin'"
  end
end

Now remove the boilerplate in our test file, so it looks like this:

defmodule ChonkOMeterTest do
  use ExUnit.Case
  doctest ChonkOMeter
end

Run the tests to ensure there are none for now:

mix test

Finally, in our README, we can add the usual doctest syntax:

<!-- README START -->

Chonk O Meter is a state-of-the-art size estimator. It will rate the size of anything according to the following chart:

![alt chart showing cats of various sizes](./images/chonk.jpg)

For example:

    iex> ChonkOMeter.story_points(10)
    "Mega Chonk"

<!-- README END -->

If you run the tests, you will notice that the change in the README has not triggered a re-compilation, meaning the app still thinks there are no doctests. To fix this, we just need to add an @external_resource module attribute into the main module. This tells mix to recompile when the README changes:

defmodule ChonkOMeter do
  @external_resource Path.expand("./README.md")
  # ^^ Add this line ^^
  @moduledoc File.read!(Path.expand("./README.md"))
             |> String.split("<!-- README START -->")
             |> Enum.at(1)
             |> String.split("<!-- README END -->")

  @doc """
  Returns the Chonk rating for a given number of story points.
  """
  def story_points(points) when is_integer(points) and points >= 0 and points < 3 do
    "A Fine Boi"
  end

  def story_points(points) when is_integer(points) and points >= 3 and points < 5 do
    "He Chomnk"
  end

  def story_points(points) when is_integer(points) and points >= 5 and points < 8 do
    "A Heckin' Chonker"
  end

  def story_points(points) when is_integer(points) and points >= 8 and points < 10 do
    "H E F T Y C H O N K"
  end

  def story_points(points) when is_integer(points) and points >= 10 and points < 15 do
    "Mega Chonk"
  end

  def story_points(points) when is_integer(points) and points >= 15 do
    "Oh Lawd He Comin'"
  end
end

When we run our tests, this now results in one passing doctest! We can also add a doctest to our function doc like so:

...
  @doc """
  Returns the Chonk rating for a given number of story points.

      iex> ChonkOMeter.story_points(5)
      "A Heckin' Chonker"
  """
  def story_points(points) when is_integer(points) and points >= 0 and points < 3 do
    "A Fine Boi"
  end

  def story_points(points) when is_integer(points) and points >= 3 and points < 5 do
    "He Chomnk"
  end

  def story_points(points) when is_integer(points) and points >= 5 and points < 8 do
    "A Heckin' Chonker"
  end

  def story_points(points) when is_integer(points) and points >= 8 and points < 10 do
    "H E F T Y C H O N K"
  end

  def story_points(points) when is_integer(points) and points >= 10 and points < 15 do
    "Mega Chonk"
  end

  def story_points(points) when is_integer(points) and points >= 15 do
    "Oh Lawd He Comin'"
  end
...

Adding Livebook to Elixir

So let's recap. Right now, we have a README as the source of truth for our moduledoc. We can have doctests and images and all the usual goodies that a moduledoc is allowed, but we don't have to repeat ourselves and risk copy/paste errors.

We want to keep that same energy going for our Livebook, to avoid repeating ourselves manually, but still have an interactive playground for our library on top of the usual moduledocs.

To do that, we can generate our Livebook from our module. To help with this, I've written a library we can include called livebook_helpers:

defp deps do
  [
    {:ex_doc, ">= 0.0.0", runtime: false, only: [:docs, :dev]},
    {:livebook_helpers, ">= 0.0.0", only: [:docs, :dev]},
  ]
end

Once we have fetched the deps with mix deps.get, running mix help shows one extra mix task:

...
mix create_livebook_from_module # Creates a livebook from the docs in the given module.
...

We can see from the docs that we run the mix task by providing a module and a path to a Livebook. Let's try that:

mix create_livebook_from_module ChonkOMeter "chonk_o_meter_introduction"

You should see a successful output that links to the generated Livebook! 🎉 There is one last thing we can do to make our workflow seamless. Let's add create_livebook_from_module to the end of the mix docs command.

defmodule ChonkOMeter.MixProject do
  use Mix.Project

  def project do
    [
      ...
      aliases: aliases(),
      ...
    ]
  end

  defp aliases() do
    [docs: ["docs", &copy_pictures/1, &create_livebook/1]]
  end

  defp copy_pictures(_) do
    File.cp_r(Path.expand("./images/"), Path.expand("./doc/images/"))
  end

  defp create_livebook(_) do
    Mix.Task.run("create_livebook_from_module", ["ChonkOMeter", "chonk_o_meter_introduction"])
  end
end

Whenever we run mix docs, we will copy over any static images used in the README and generate a Livebook from our main module!

Running Livebook in Elixir

So far, so good! We have a nice pipeline to create a useful Livebook, but now we need to think about running the Livebook. Start the Livebook app like so:

livebook server

By default, the Elixir sections only have access to the Elixir and Erlang standard library. If we run our generated library and then attempt to run an Elixir cell that calls the library, it will fail because the library code is not there. To solve this, we have two options — Mix.install or Livebook runtime.

Add `Mix.install` to Livebook

We could add a section to the beginning of the Livebook that does this:

Mix.install([:chonk_o_meter])

When called, we will get the latest version of the library from Hex. It will be made available to all subsequent Elixir cells, just like when you run Mix.install inside an IEx REPL.

You can also easily specify a version and provide live documentation for any version of a given library:

Mix.install([{chonk_o_meter: ">=0.0.1"}])

LivebookHelpers can even generate a Livebook with a Mix.install at the beginning if we supply deps to the mix task:

mix create_livebook_from_module ChonkOMeter "chonk_o_meter_introduction" "[:chonk_o_meter"]"

This works great for any library that is deployed to Hex. However, you'll run into problems if, for example, you want a Livebook for a main branch. In that case, you can do this:

Mix.install [{:chonk_o_meter, path: "./"}]

This tells mix to look in the provided path for a local version of the library. This, of course, makes some assumptions about where the Livebook will run, so it's good to make that clear. If you put the Livebook at the root of the repo and a user starts the Livebook server from there, then the path "./" will work.

If you don't want to rely on this, though, Livebook has your back with a powerful feature: runtime!

Livebook Runtime

There are three kinds of runtime, but they all let you point to code and call it in any Elixir cell within your Livebook.

The three runtime options are:

Embedded
Attached node
Mix standalone

You select the runtime by clicking the cog symbol here:

Let's look at each runtime option below.

Embedded Mode

Embedded Mode lets us run the notebook code within the Livebook node itself! This is really for specific cases where there is no option to start a separate Elixir runtime — for example, on embedded devices.

Code defined in one notebook may interfere with code from another notebook. So this mode should only be used if you have no alternative and is not relevant here.

Attached Node

The attached node runtime connects a Livebook to a running Elixir app via the usual Erlang magic that we use to connect two running nodes. It looks like this:

As long as the app starts with a cookie that you know and a sname, you can give them to Livebook and connect. This is like getting a remote shell in a running app but with a more full-featured text-editing environment.

Using an attached node gives you complete control over how your app starts. You get much more control than the mix standalone and can do all sorts of things, like set env vars and start other services (like a database).

An attached node could be especially relevant for creating internal (live!) documentation for closed-source repos at work, but is not relevant for us and our library.

Mix Standalone

Finally, the Mix standalone runtime lets you point to a mix project which Livebook will compile and start (analogous to running iex -S mix in your terminal).

Mix standalone confers a great advantage over Mix.install, as you can recompile it! It's useful if you write a Livebook from scratch; in that case, you'll likely add something to the library that you'll then want to use in the Livebook.

Instead of having to kill the Livebook server and restart to access the new functions, you can add an Elixir cell with the following:

IEx.Helpers.recompile()

This will recompile the connected mix app (i.e., our library) when you call it, meaning you get access to any new functionality therein.

Livebook for Docs: Try It Yourself in Your Elixir App

That concludes our tour of Livebook for docs. You can see the chonk_o_meter library example here. For an example of these ideas in action in a real library, check out my data_schema library too.

Currently, GitHub doesn't recognize the .livemd extension, so if you play around with Livebook, I would encourage you to push to public repos. The more we do this, the more chance we have of getting GitHub to parse the files with nice syntax highlighting and markdown rendering.

Until that happens, though, we can put a magic line at the top of a Livebook to force GitHub to render it as markdown:

<!-- vim: syntax=markdown -->

The Livebook that Livebook helpers generates will include this line for you. Now you have all the knowledge you need go forth and create live docs!

Happy coding!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

8 Common Causes of Flaky Tests in Elixir

Adz — Tue, 04 Jan 2022 13:20:18 +0000

Flaky tests are like meme stocks — many people have them, but no one knows what to do with them. Today, we will change that by diving into some common causes and, more importantly, solutions for flickering tests in Elixir.

Elixir has many great primitives that let us run tests asynchronously, including immutable data, lightweight processes, and the Ecto SQL sandbox. Running tests asynchronously can greatly speed up your test suite, but can also increase the chance of flaky tests.

What Are Flaky Tests?

Flaky tests are tests that sometimes fail. They erode confidence in your test suite and are hard to fix because they are hard to reproduce. Often they imply a test is broken (rather than the code) and so are ignored or retried until they work.

Locally, this slows you down, but it especially hurts your CI — every failure means at least one rebuild. Anything that doubles the time it takes to deploy code is very annoying. The culture of "oh, just retry" is a broken window that risks further decline in your codebase.

Find and Replicate Flaky Tests in Elixir

Flaky tests are usually easy to spot (they'll be the ones that fail on CI when you update the README), but they are harder to replicate locally.

Here, we can use ExUnit to try and help because it gives us the ability to run the tests in the same order as a previous test run. Usually, we run tests randomly to help encourage test isolation, but we can seed that randomness with a command-line option. Re-using the seed for a previous run will trigger the tests in the same order each time the seed is used. ExUnit outputs the used seed here:

Finished in 0.5 seconds (0.00s async, 0.5s sync)
91 tests, 0 failures

Randomized with seed 119489
#          The seed  ^^^^

We can re-use that seed like this:

mix test --seed 119489

However, this won't always reproduce the flake, especially if a database is the cause of the flakiness or if some resource constraint makes the flakiness more likely (CI is likely to have much less RAM, for example, than your dev machine). On top of that, the seed does not influence how quickly a test runs. If the tests run asynchronously, there is no guarantee that two tests will run at the same time again (even if they are triggered in the same order).

Imagine three tests are running concurrently: A, B, and C. The seed determines that the tests trigger in order A, B, and C. The first time these tests run, test A takes as long as the other two to finish. A starts, then B triggers and finishes, C triggers and finishes, and finally A finishes.

If we rerun these tests with the same seed, even though they trigger in the same order, A might finish before C starts this time, for whatever reason. That might mean you won't reproduce the conditions needed for the test to flicker. Using a seed is a good first stab, but it might not work.

Running the tests repeatedly can help. Here is a bash function that will run the tests until there is a failure:

function test_repeat {
  while mix test
  do
    echo "testing"
  done
}

When you understand some of the common causes of flaky tests, you can often identify the problem just by looking. That's the level of intuition we want to build up here.

All flaky tests boil down to one thing: non-determinism. Non-determinism is when the same input can produce different results. We need to look out for non-determinism sneaking into our tests and think about how it can happen when tests run asynchronously.

Especially look out for the global state. Global state, I hear you say? But Elixir is functional! There is no global state! Well...that's not quite true.

Let's take some of the most common causes of flaky tests in turn below.

8 Common Causes of Flaky Tests

1. Using `Application.put_env` in Asynchronous Tests

When configuring Elixir apps, we can read values from the config using functions like Application.fetch_env!/2. You might be tempted to set an application state in the test setup to test behavior in different environments:

defmodule MyTest do
  use ExUnit.Case, async: true

  describe "on CI" do
    setup do
      old_value = Application.fetch_env!(:my_app, :is_CI)
      Application.put_env(:my_app, :is_CI, true)
      on_exit(fn -> Application.put_env(:my_app, :is_CI, old_value) end)
    end

    test "Does a thing!" do
      assert MyModule.fun == 1
    end
  end

  describe "Not on CI" do
    setup do
      old_value = Application.fetch_env!(:my_app, :is_CI)
      Application.put_env(:my_app, :is_CI, false)
      on_exit(fn -> Application.put_env(:my_app, :is_CI, old_value) end)
    end

    test "Does not do the thing" do
      assert MyModule.fun == 2
    end
  end
end

Don't do this if your tests run asynchronously. Application.fetch_env/2 can be called from anywhere, meaning it is effectively a global state. And worse than that, because you can Application.put_env/3 anywhere, it is effectively a global mutable state.

That means even if you reset the application, another asynchronous running test might read from the application after you have changed it (but before your test completes and changes it back). That test gets the wrong value and potentially fails, sometimes.

The Fix

Don't use Application.put_env in tests — or, if you have to, put it in a test with async: false and reset it using on_exit().

2. Incorrectly Configuring `Ecto.SQL.Sandbox`

Usually, we configure Ecto so that each test runs in its own transaction. Each test runs concurrently in its own process, and each process opens its own transaction to the database.

This is great because it means that Ecto can simply roll back that transaction when the test finishes. This allows us to run our tests asynchronously (in Postgres at least) without worrying that the state of the database is anything other than what our test specifies it to be.

However, sometimes we need to see what other processes do to a database. Imagine we test some code that starts a task that writes to the database. The test process needs to see what that task's process does to the database.

We can do this by putting Ecto.AdaptersSQL.Sandbox in :shared mode, allowing "a process to share its connection with any other process automatically".

But remember that each asynchronous test runs in its own process. That means that in :shared mode, any test running simultaneously with another test will share the transaction to the database and see all of the changes the other test makes.

This is the first way we could introduce non-determinism in tests.

The Fix

If a test sets the Ecto.Adapters.SQL.Sandbox to :shared mode, never run it asynchronously, like so:

defmodule MyTest do
  @moduledoc """
  This test should be synchronous because the sandbox runs in shared mode for it!
  """
  useExUnit.Case, async: false

  describe "my_fun/2" do
    ...
  end
end

3. Having Non-unique Unique Data

Different databases implement transactions slightly differently. For now, I will talk about the most commonly used database in Elixir: Postgres.

Postgres

Postgres never lets a transaction see another's uncommitted changes (even though the sql standard technically allows it!), so the default transaction isolation level doesn't cause problems in concurrent tests.

Unfortunately, two concurrently running tests can still interfere via a different concurrency control that Postgres employs: locks.

A lock is a concurrency control mechanism that ensures different commands can be executed safely while other commands are happening. For example, if we wish to truncate a table, it isn't a good idea to try to insert something into that table at the same time. Truncate "locks" the table, preventing anything else from happening to that table while it is being truncated.

You can use explicit locking — where you tell Postgres to take a specific kind of lock — but each command has its own appropriate level of automatic locking. If Postgres thinks two concurrently running commands will conflict, the second command will wait for the first to complete.

By far, the most common problem here is with unique data. Let's say we have a user table with a unique email address. Now, let's imagine we have test 1 and 2, and both insert a user with the same email address — jeff@example.com — as part of the test setup.

When checking a unique index on insertion, Postgres will look at uncommitted transactions to find out if it can continue. Otherwise, it checks the index just before it inserts and ends up with two non-unique rows.

If test 1 intends to insert a user with the email jeff@example.com, test 2 cannot do that. But if, later on, test 1 never actually inserts them, then test 2 can insert their user. That means that Postgres can't know the answer to "can test 2 insert the user?" until after test 1 has finished. So it takes a lock on the row, which basically says: "hey test 2, wait until test 1 has finished its transaction before you continue".

Even though they happen in different isolated transactions that never actually commit, when Postgres sees one transaction has already "inserted" a row with a jeff@example.com email,
it figures out the next one has to wait for the first transaction to finish or rollback.

All this means that if you have data that should be unique but isn't across concurrently running tests, you will at best incur some performance penalty. This can be quite severe as it adds up across the codebase. You can end up with async tests effectively running synchronously!

But, if we add more tables with more unique columns that are not unique across tests, it gets even worse! Depending on the order in which data is set up, you can end up with deadlocks. Let's say our app has blogs with a unique title. Picture the following:

Test 1                                      Test 2

inserts user with email jeff@example.com
                                            inserts a blog with title "Deadlocks!"
                                            inserts with email jeff@example.com

inserts a blog with title "Deadlocks!"

Test 1 inserts the user. Before test 2 can do the same, it must get a lock and wait for test 1 to finish.
Now test 2 inserts a blog, and for test 1 to do that, it must wait for test 2 to finish.
Then test 2 attempts to insert the user, so it gets the lock and says "I'll wait for test 1". At this point, test 2 is waiting for test 1 to finish.

Meanwhile, test 1 continues and attempts to insert the blog but can't because test 2 just did. So it waits to see if test 2 will commit or rollback. But test 2 is waiting for test 1 to finish, and now test 1 is waiting for test 2 to finish!

This is a deadlock. Usually, Postgres detects them automatically and one transaction gets rolled back, causing your test to flake.

The Fix

Sometimes you will hear advice like "ensure that the locks are acquired in a consistent order". This helps prevent a deadlock, but is tricky to do and would still incur the performance penalty mentioned.

The simplest golden rule is — if your data should be unique, make it unique across all tests:

%User{email: "#{Ecto.UUID.bingenerate}@example.com"}

Really consider if your test data is unique as well. Using a uuid will make it unique. Picking a random number between 1 and 1,000 will not make it unique.

4. Writing to ETS or Persistent Term in Asynchronous Tests

ETS and persistent term are two data stores that come with Erlang. They are accessible from anywhere and, like all data stores, are stateful. That means if we have two tests running at the same time that set themselves up by writing into ETS or persistent term they can — and will — interfere with each other. For example, one test adds a record to the data store then deletes it, while another test asserts the number of records in that same table. They will interfere with each other.

The Fix

Your options are mock ets/persistent_term — after all, we don't need to test that these things do what they say (Erlang does that for us!) — or have the tests run synchronously. Prefer the former! Mox is a great choice for this sort of work.

5. Relying On The Order Of Logs

Sometimes you may want to test that a particular log line has been emitted. The best way to do this is with ExUnit's capture log:

logs = ExUnit.capture_log(fn -> MyFun.call() end)
assert logs == "This is my Log. There are many like it but this one is mine."

This takes a function and captures all of the logs emitted during the execution of that function. It concatenates all the logs together into one binary and returns it.

But logs can be emitted from anywhere, and capture_log will capture them dutifully, making them, in a sense, global. And because capture_log concatenates all logs together, each new log line changes the result of capture_log. So, in effect, the returned binary is global and changing.

If this has set off warning bells: congratulations, you are right to be worried! If the tests are running asynchronously the result of capture_log will be different depending on what other tests are running at the time. If you assert what the captured logs should exactly look like, you will have a bad time.

The same principle applies if you use something like a Ring Logger or any custom logging backend that buffers the logs.

The Fix

Never rely on log order when making assertions. Assume that the log can include any number of other log lines. For assert capture, you can use regex's or the =~ operator to match on the subset of the log that you care about:

logs = ExUnit.capture_log(fn -> MyFun.call() end)
assert logs =~ "This is my Log. There are many like it but this one is mine."

That way, the rest of the logs do not interfere with your assertions.

6. Failing to Specify Order in the Database

The most common cause of flaky tests in the wild is the assumption that a database will return results in a certain order when there is no such guarantee. In Postgres, for example, if an explicit order is not supplied then the results can be ordered in any way — even if it seems otherwise, most of the time! So all of these are bad ideas:

# No order, no guarantee!
assert Repo.all(Stuffs) == [first, second]

# Pattern matching wont help you here.
[first, second] = Repo.all(my_query)
assert first.thing == 1

# A preload also doesn't specify an order.
%MyModel{comments: [first_comment | _]} = Repo.get(MyModel, 1) |> Repo.preload(:comments)
assert first_comment.text == "Oh No!"

The Fix

Some possible solutions are:

Specify the order in the database query:

assert Repo.all(from(s in Stuffs, order_by: [s.inserted_at])) == [first, second]

But wait, did you notice the problem above? What if the records have the same inserted_at — the sort isn't guaranteed to be stable. You need to handle that possibility too, e.g., if the id is an auto_incrementing integer, you could:

result = Repo.all(from(s in Stuffs, order_by: [s.inserted_at, s.id]))
assert result == [first, second]

Don't assert on order if it's not important:

result = Repo.all(Stuffs)
assert_unordered_list_equality(result, [first, second])

Or even:

all = Repo.all(Stuffs)

assert length(all) == 2

jeff = Enum.find(all, & &1.name == "Jeff")
assert jeff == %{...}

joe = Enum.find(all, & &1.name == "Joe")
assert joe == %{...}

7. Not Mocking Date/Time/Random ⏰

We've all been there. It's 2 PM on Wednesday, and for some reason, half the test suite fails when it all passed a minute ago. Yes, someone forgot to mock date time.

Imagine we have this function:

def is_in_the_past?(date) do
  Date.compare(date, Date.utc_today()) == :lt
end

Now we add a test that looks like this:

test "returns false when the date is in the past" do
  date = ~D[2022-11-05]
  assert is_in_the_past?(date) == false
end

Well, this will work until after 5th November 2022. This same idea can apply to Times, Dates, DateTimes, NaiveDateTimes, and any function that uses random — for example, Enum.take_random or the like.

The Fix

Mock those modules! Mox is a great choice for this sort of work.

8. Using `assert_received/2` Instead of `assert_receive/3`

In ExUnit you can assert that a test process receives a message using either assert_receive/3 or assert_received/2. This lets you write tests for functions that spin up processes and send messages to other ones, e.g.:

defmodule Echo do
  def echo(pid, message) do
    send(pid, message)
  end
end

test "Echo.echo/2 sends the right message to the given pid" do
  ref = make_ref()

  Echo.echo(self(), {ref, :hello})

  assert_received({^ref, :hello})
end

But there is a subtle difference between the two assertions — assert_receive/3 allows a timeout. This is an amount of time to wait for the message to appear in the current process's mailbox. Usually, this is all very quick, so a timeout is not needed, but send in elixir is non-blocking.

The send inside Ecto.echo happens, then immediately, we continue with our test. The next thing is to check the mailbox. In the right conditions (i.e., some performance blip), there is a small chance that assert_received/2 could look in the mailbox after the send happens but before the message reaches the inbox of the current process. If this does happen, we have a flaky test.

The Fix

Prefer assert_receive/3. Remember, the timeout is the maximum time it will wait — if the message gets there sooner, the test will finish sooner.

A Side-note: Should Tests Run Sync or Async?

You may have noticed that the chance of flickering tests decreases greatly if we make all tests synchronous. I do not recommend doing that. Running asynchronously greatly speeds up most test suites.

Similarly, mocking everything and writing only unit tests will also likely reduce the chance of flickering — but it's on us to decide whether such a testing strategy would give us enough confidence in our code.

One thing to note is that tests within a test file always run synchronously. If the file is marked to run async, the module might run at the same time that another module of tests runs. So, if you really need to have some synchronous tests, you can put them in their own module (in the same file). That allows most of the tests to run async:

defmodule MyTest do
  use ExUnit.Case, async: true

  test "my_fun/3" do
    ...
  end
end

defmodule MySynchronousTest do
  @moduledoc "These tests are synchronous because blah blah..."
  use ExUnit.Case, async: false

  describe "my_fun/2" do
    ...
  end
end

Wrap up

In this post, we've defined flaky tests and seen how to replicate them, before running through 8 common causes of flaky tests and their fixes.

Here is a summary of what you should avoid doing, for easy reference:

Don't use Application.put_env in async tests.
Don't use :shared mode on the Ecto sql sandbox in async tests.
Ensure unique data is unique across all tests.
Never rely on the order of logs in a test.
Consider mocking ETS/:persistent_term for testing.
If you rely on database order, specify it.
Mock dates, times, datetimes, and random.
Prefer assert_receive/3 over assert_received/2

I hope you've found this post useful, and happy coding!

P.S. If you'd like to read Elixir Alchemy posts as soon as they get off the press, subscribe to our Elixir Alchemy newsletter and never miss a single post!

DEV Community: Adz

Phoenix 1.7 for Elixir: Edit a Form in a Modal

Editing a Form in a Modal

Icons in Phoenix

Back to Editing Our Form

Add the open_edit_modal Function

Debugging an Issue with the open_edit_modal

Fixing the Issue

Implementing the Update in Our Phoenix Application

Wrapping Up

Add a Form to a Modal in Phoenix 1.7

Adding a Form to Our Phoenix Application

Phoenix's Component to_form

Using to_form

Saving the Form

Closing the Modal with push_event

Wrapping Up

Create and Open a Modal in Phoenix 1.7

The UI of Our Phoenix App — Setup

What Is a Modal in Phoenix?

What Are attrs and Slots?

Making the Modal Appear in Phoenix

Calling the show_modal Function

Wrapping Up

Faster XML Parsing with Elixir

XML Parsing with Elixir — An Introduction

Three Approaches to XML Parsing with Elixir

Building a DOM

Virtual Token Descriptor (VTD) in Elixir

VTD to XML Parsing: An Example

Trade-offs of VTD

SAX Parsing in Elixir

SAX Parsing: An Example

Trade-offs of a Stack

Querying the DOM with DataSchema

How DataSchema Works

XML Parsing with Elixir: Taking it One Step Further

Wrap Up

Livebook for Elixir: Just What the Docs Ordered

But First: What is Livebook for Elixir?

Livebook Docs: A Single Source of Truth in Elixir

Adding an Image to the Moduledoc

Doctests in Elixir's Livebook

Adding Livebook to Elixir

Running Livebook in Elixir

Add Mix.install to Livebook

Livebook Runtime

Embedded Mode

Attached Node

Mix Standalone

Livebook for Docs: Try It Yourself in Your Elixir App

8 Common Causes of Flaky Tests in Elixir

What Are Flaky Tests?

Find and Replicate Flaky Tests in Elixir

8 Common Causes of Flaky Tests

1. Using Application.put_env in Asynchronous Tests

The Fix

2. Incorrectly Configuring Ecto.SQL.Sandbox

The Fix

3. Having Non-unique Unique Data

Postgres

The Fix

4. Writing to ETS or Persistent Term in Asynchronous Tests

The Fix

5. Relying On The Order Of Logs

The Fix

6. Failing to Specify Order in the Database

The Fix

7. Not Mocking Date/Time/Random ⏰

The Fix

8. Using assert_received/2 Instead of assert_receive/3

The Fix

A Side-note: Should Tests Run Sync or Async?

Wrap up

Add the `open_edit_modal` Function

Debugging an Issue with the `open_edit_modal`

Phoenix's Component `to_form`

Using `to_form`

Closing the Modal with `push_event`

What Are `attr`s and Slots?

Calling the `show_modal` Function

Add `Mix.install` to Livebook

1. Using `Application.put_env` in Asynchronous Tests

2. Incorrectly Configuring `Ecto.SQL.Sandbox`

8. Using `assert_received/2` Instead of `assert_receive/3`