Awesome

Phoenix Chat Example

phoenix-chat-logo

GitHub Workflow Status

A step-by-step tutorial for building, testing and deploying a Chat app in Phoenix!

</div>

Phoenix Chat Example
- Why?
- What?
- Who?
How?
Testing our App (Automated Testing)
Authentication
Adding Presence to track who's online
Continuous Integration
Deployment!

Why?

Chat apps are the "Hello World" of real time examples.

Sadly, most example apps show a few basics and then ignore the rest ... 🤷‍♀️ So beginners are often left lost or confused as to what they should do or learn next! Very few tutorials consider Testing, Deployment, Documentation or other "Enhancements" which are all part of the "Real World" of building and running apps; so those are topics we will cover to "fill in the gaps".

We wrote this tutorial to be easiest way to learn Phoenix, Ecto and Channels with a practical example anyone can follow.

This is the example/tutorial we wished we had when we were learning Elixir, Phoenix ... If you find it useful, please ⭐ 🙏 Thanks!

What?

A simple step-by-step tutorial showing you how to:

Create a Phoenix App from scratch (using the mix phx.new chat "generator" command)
Add a "Channel" so your app can communicate over WebSockets.
Implement a basic front-end in plain JavaScript (ES5 without any libraries) to interact with Phoenix (send/receive messages via WebSockets)
Add a simple "Ecto" schema to define the Database Table (to store messages)
Write the functions ("CRUD") to save message/sender data to a database table.
Test that everything is working as expected.
Deploy to Fly.io so you can show people your creation!

Initially, we deliberately skip over configuration files and "Phoenix Internals" because you (beginners) don't need to know about them to get started. But don't worry, we will return to them when needed. We favour "just-in-time" (when you need it) learning as it's immediately obvious and practical why we are learning something.

Who?

This example is for complete beginners as a "My First Phoenix" App.

We try to assume as little as possible, but if you think we "skipped a step" or you feel "stuck" for any reason, or have any questions (related to this example), please open an issue on GitHub! Both the @dwyl and Phoenix communities are super beginner-friendly, so don't be afraid/shy. Also, by asking questions, you are helping everyone that is or might be stuck with the same thing!

Chat App specific questions: dwyl/phoenix-chat-example/issues
General Learning Phoenix questions: dwyl/learn-phoenix-framework/issues

How?

These instructions show you how to create the Chat app from scratch.

0. Pre-requisites (Before you Start)

Elixir Installed on your local machine. see: dwyl/learn-elixir#installation e.g:

brew install elixir

Note: if you already have Elixir installed on your Mac, and just want to upgrade to the latest version, run: brew upgrade elixir

Phoenix framework installed. see: hexdocs.pm/phoenix/installation.html e.g:

mix archive.install hex phx_new

PostgreSQL (Database Server) installed (to save chat messages) see: dwyl/learn-postgresql#installation

Basic Elixir Syntax knowledge will help, please see: dwyl/learn-elixir
Basic JavaScript knowledge is advantageous (but not essential as the "front-end" code is quite basic and well-commented). see: dwyl/Javascript-the-Good-Parts-notes

Check You Have Everything Before Starting

Check you have the latest version of Elixir (run the following command in your terminal):

elixir -v

You should see something like:

Erlang/OTP 25 [erts-13.1.1] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1] [jit] [dtrace]

Elixir 1.14.1 (compiled with Erlang/OTP 25)

Check you have the latest version of Phoenix:

mix phx.new -v

You should see:

Phoenix installer v1.7.0-rc.2

Note: if your Phoenix version is newer, Please feel free to update this doc! 📝 We try our best to keep it updated ... but your contributions are always welcome!

In this tutorial, we are using Phoenix 1.7-rc2, the second release candidate for Phoenix 1.7. At the time of writing, if you install Phoenix, the latest stable version is not v1.7. To use this version, follow the official guide (don't worry, it's just running one command!) -> https://www.phoenixframework.org/blog/phoenix-1.7-released

However, if you are reading this after its release, v1.7 will be installed for you, and you should see Phoenix installer v1.7.0 in your terminal.

Confirm PostgreSQL is running (so the App can store chat messages) run the following command:

lsof -i :5432

You should see output similar to the following:

COMMAND  PID  USER   FD  TYPE DEVICE                  SIZE/OFF NODE NAME
postgres 529 Nelson  5u  IPv6 0xbc5d729e529f062b      0t0  TCP localhost:postgresql (LISTEN)
postgres 529 Nelson  6u  IPv4 0xbc5d729e55a89a13      0t0  TCP localhost:postgresql (LISTEN)

This tells us that PostgreSQL is "listening" on TCP Port 5432 (the default port)

If the lsof command does not yield any result in your terminal, run:

pg_isready

It should print the following:

/tmp:5432 - accepting connections

With all those "pre-flight checks" performed, let's fly! 🚀

First Run the Finished App

Before you attempt to build the Chat App from scratch, clone and run the finished working version to get an idea of what to expect.

Clone the Project:

In your terminal run the following command to clone the repo:

git clone git@github.com:dwyl/phoenix-chat-example.git

Install the Dependencies

Change into the phoenix-chat-example directory and install both the Elixir and Node.js dependencies with this command:

cd phoenix-chat-example
mix setup

Run the App

Run the Phoenix app with the command:

mix phx.server

If you open the app localhost:4000 in two more web browsers, you can see the chat messages displayed in all of them as soon as you hit the <kbd>Enter</kbd> key:

phoenix-chat-example-tailwind-ui-with-auth

Now that you have confirmed that the finished phoenix chat app works on your machine, it's time to build it from scratch!

Change directory:

cd ..

And start building!

1. Create The App

In your terminal program on your localhost, type the following command to create the app:

mix phx.new chat --no-mailer --no-dashboard --no-gettext

That will create the directory structure and project files.

We are running the mix phx.new command with the --no-mailer --no-dashboard --no-gettext arguments because we don't want our project to generate mailer files, to include a Phoenix.LiveDashboard and generate gettext files (for i18n).

When asked to "Fetch and install dependencies? [Yn]", Type <kbd>Y</kbd> in your terminal, followed by the <kbd>Enter</kbd> (<kbd>Return</kbd>) key.

You should see: fetch-and-install-dependencies

Change directory into the chat directory by running the suggested command:

cd chat

Now run the following command:

mix setup

Note: at this point there is already an "App" it just does not do anything (yet) ... you can run mix phx.server in your terminal - don't worry if you're seeing error messages, this is because we haven't created our database yet. We will take care of that in step 6! For now, open http://localhost:4000 in your browser and you will see the default "Welcome to Phoenix" homepage:

welcome-to-phoenix

Shut down the Phoenix server in your terminal with the <kbd>ctrl</kbd>+<kbd>C</kbd> command.

Run the Tests

In your terminal window, run the following command:

mix test

You should see output similar to the following:

Generated chat app
.....
Finished in 0.02 seconds (0.02s async, 0.00s sync)
5 tests, 0 failures

Randomized with seed 84184

Now that we have confirmed that everything is working (all tests pass), let's continue to the interesting part!

2. Create the (WebSocket) "Channel"

Generate the (WebSocket) channel to be used in the chat app:

mix phx.gen.channel Room

If you are prompted to confirm installation of a new socket handler type y and hit the [Enter] key.

This will create three files:

* creating lib/chat_web/channels/room_channel.ex
* creating test/chat_web/channels/room_channel_test.exs
* creating test/support/channel_case.ex

in addition to creating two more files:

* creating lib/chat_web/channels/user_socket.ex
* creating assets/js/user_socket.js

The room_channel.ex file handles receiving/sending messages and the room_channel_test.exs tests basic interaction with the channel. We'll focus on the socket files created afterwards. (Don't worry about this yet, we will look at the test file in step 14 below!)

We are informed that we need to update a piece of code in our app:

Add the socket handler to your `lib/chat_web/endpoint.ex`, for example:

    socket "/socket", ChatWeb.UserSocket,
      websocket: true,
      longpoll: false

For the front-end integration, you need to import the `user_socket.js`
in your `assets/js/app.js` file:

    import "./user_socket.js"

The generator asks us to import the client code in the frontend. Let's do that later. For now, open the lib/chat_web/endpoint.ex file and follow the instructions.

After this, open the file called /lib/chat_web/channels/user_socket.ex and change the line:

channel "room:*", ChatWeb.RoomChannel

to:

channel "room:lobby", ChatWeb.RoomChannel

Check the change here.

This will ensure that whatever messages that are sent to "room:lobby" are routed to our RoomChannel.

The previous "room.* meant that any subtopic within "room" were routed. But for now, let's narrow down to just one subtopic :smile:.

For more detail on Phoenix Channels, (we highly recommend you) read: https://hexdocs.pm/phoenix/channels.html

3. Update the Template File (UI)

Open the the /lib/chat_web/controllers/page_html/home.html.heex file and copy-paste (or type) the following code:

<!-- The list of messages will appear here: -->
<div class="mt-[4rem]">
  <ul id="msg-list" phx-update="append" class="pa-1"></ul>
</div>

<footer class="bg-slate-800 p-2 h-[3rem] fixed bottom-0 w-full flex justify-center">
  <div class="w-full flex flex-row items-center text-gray-700 focus:outline-none font-normal">
    <input type="text" id="name" placeholder="Name" required
        class="grow-0 w-1/6 px-1.5 py-1.5"/>

    <input type="text" id="msg" placeholder="Your message" required
      class="grow w-2/3 mx-1 px-2 py-1.5"/>

    <button id="send" class="text-white bold rounded px-3 py-1.5 w-fit
        transition-colors duration-150 bg-sky-500 hover:bg-sky-600">
      Send
    </button>
  </div>
</footer>

This is the basic form we will use to input Chat messages. The classes e.g. w-full and items-center are TailwindCSS classes to style the form. Phoenix includes Tailwind by default so you can get up-and-running with your App/Idea/"MVP"!

If you're new to Tailwind, please see: dwyl/learn-tailwind

If you have questions about any of the Tailwind classes used, please spend 2 mins Googling or searching the official (superb!) docs: tailwindcss.com/docs and then if you're still stuck, please open an issue.

Your home.html.heex template file should look like this: /lib/chat_web/controllers/page_html/home.html.heex

3.1 Update Layout Template

Open the lib/chat_web/components/layouts/root.html.heex file and locate the <body> tag. Replace the contents of the <body> with the following code:

  <body class="bg-white antialiased min-h-screen flex flex-col">
    <header class="bg-slate-800 w-full h-[4rem] top-0 fixed flex flex-col justify-center z-10">
      <div class="flex flex-row justify-center items-center">
        <h1 class="w-4/5 md:text-3xl text-center font-mono text-white">
          Phoenix Chat Example
        </h1>
      </div>
    </header>
    <%= @inner_content %>
  </body>

Your root.html.heex template file should look like this: /lib/chat_web/components/layouts/root.html.heex

At the end of this step, if you run the Phoenix Server mix phx.server, and view the App in your browser it will look like this:

phoenix-chat-blank

So it's already starting to look like a basic Chat App. Sadly, since we changed the copy of the home.html.heex our page_controller_test.exs now fails:

Run the command:

mix test

1) test GET / (ChatWeb.PageControllerTest)
     test/chat_web/controllers/page_controller_test.exs:4
     Assertion with =~ failed
     code:  assert html_response(conn, 200) =~ "Peace of mind from prototype to production"

Thankfully this is easy to fix.

3.2 Update the `page_controller_test.exs`

Open the test/chat_web/controllers/page_controller_test.exs file and replace the line:

    assert html_response(conn, 200) =~ "Peace of mind from prototype to production"

With:

    assert html_response(conn, 200) =~ "Phoenix Chat Example"

Now if you run the tests again, they will pass:

mix test

Sample output:

........
Finished in 0.1 seconds (0.09s async, 0.06s sync)
8 tests, 0 failures

Randomized with seed 275786

4. Update the "Client" code in App.js

Open assets/js/app.js, uncomment and change the line:

import socket from "./user_socket.js"

With the line uncommented, our app will import the socket.js file which will give us WebSocket functionality.

Then add the following JavaScript ("Client") code to the bottom of the file:

/* Message list code */
const ul = document.getElementById('msg-list');    // list of messages.
const name = document.getElementById('name');      // name of message sender
const msg = document.getElementById('msg');        // message input field
const send = document.getElementById('send');      // send button

const channel = socket.channel('room:lobby', {});  // connect to chat "room"
channel.join(); // join the channel.

// Listening to 'shout' events
channel.on('shout', function (payload) {
  render_message(payload)
});


// Send the message to the server on "shout" channel
function sendMessage() {

  channel.push('shout', {        
    name: name.value || "guest", // get value of "name" of person sending the message. Set guest as default
    message: msg.value,          // get message text (value) from msg input field.
    inserted_at: new Date()      // date + time of when the message was sent
  });

  msg.value = '';                // reset the message input field for next message.
  window.scrollTo(0, document.documentElement.scrollHeight) // scroll to the end of the page on send
}

// Render the message with Tailwind styles
function render_message(payload) {

  const li = document.createElement("li"); // create new list item DOM element

  // Message HTML with Tailwind CSS Classes for layout/style:
  li.innerHTML = `
  <div class="flex flex-row w-[95%] mx-2 border-b-[1px] border-slate-300 py-2">
    <div class="text-left w-1/5 font-semibold text-slate-800 break-words">
      ${payload.name}
      <div class="text-xs mr-1">
        <span class="font-thin">${formatDate(payload.inserted_at)}</span> 
        <span>${formatTime(payload.inserted_at)}</span>
      </div>
    </div>
    <div class="flex w-3/5 mx-1 grow">
      ${payload.message}
    </div>
  </div>
  `
  // Append to list
  ul.appendChild(li);
}

// Listen for the [Enter] keypress event to send a message:
msg.addEventListener('keypress', function (event) {
  if (event.key === `Enter` && msg.value.length > 0) { // don't sent empty msg.
    sendMessage()
  }
});

// On "Send" button press
send.addEventListener('click', function (event) {
  if (msg.value.length > 0) { // don't sent empty msg.
    sendMessage()
  }
});

// Date formatting
function formatDate(datetime) {
  const m = new Date(datetime);
  return m.getUTCFullYear() + "/" 
    + ("0" + (m.getUTCMonth()+1)).slice(-2) + "/" 
    + ("0" + m.getUTCDate()).slice(-2);
}

// Time formatting
function formatTime(datetime) {
  const m = new Date(datetime);
  return ("0" + m.getUTCHours()).slice(-2) + ":"
    + ("0" + m.getUTCMinutes()).slice(-2) + ":"
    + ("0" + m.getUTCSeconds()).slice(-2);
}

Take a moment to read the JavaScript code and confirm your understanding of what it's doing. Hopefully the in-line comments are self-explanatory, but if anything is unclear, please ask!

At this point your app.js file should look like this: /assets/js/app.js

4.1 Comment Out Lines in `user_socket.js`

By default the phoenix channel (client) will subscribe to the generic room: "topic:subtopic". Since we aren't going to be using this, we can avoid seeing any "unable to join: unmatched topic" errors in our browser/console by simply commenting out a few lines in the user_socket.js file. Open the file in your editor and locate the following lines:

let channel = socket.channel("room:42", {})
channel.join()
  .receive("ok", resp => { console.log("Joined successfully", resp) })
  .receive("error", resp => { console.log("Unable to join", resp) })

Comment out the lines so they will not be executed:

//let channel = socket.channel("room:42", {})
//channel.join()
//  .receive("ok", resp => { console.log("Joined successfully", resp) })
//  .receive("error", resp => { console.log("Unable to join", resp) })

Your user_socket.js should now look like this: /assets/js/user_socket.js

If you later decide to tidy up your chat app, you can delete these commented lines from the file. We are just keeping them for reference of how to join channels and receive messages.

If you are running the app, try to fill the name and message fields and click Enter (or press Send).

The message should appear on different windows!

With this done, we can proceed.

Storing Chat Message Data/History

If we didn't want to save the chat history, we could just deploy this App immediately and we'd be done!

In fact, it could be a "use-case" / "feature" to have "ephemeral" chat without any history ... see: http://www.psstchat.com/.

But we are assuming that most chat apps save history so that new people joining the "channel" can see the history and people who are briefly "absent" can "catch up" on the history.

5. Generate Database Schema to Store Chat History

Run the following command in your terminal:

mix phx.gen.schema Message messages name:string message:string

You should see the following output:

* creating lib/chat/message.ex
* creating priv/repo/migrations/20230203114114_create_messages.exs

Remember to update your repository by running migrations:

    $ mix ecto.migrate

Let's break down that command for clarity:

mix phx.gen.schema - the mix command to create a new schema (database table)
Message - the singular name for record in our messages "collection"
messages - the name of the collection (or database table)
name:string - the name of the person sending a message, stored as a string.
message:string - the message sent by the person, also stored as a string.

The line creating lib/chat/message.ex creates the "schema" for our Message database table.

Additionally a migration file is created, e.g: creating priv/repo/migrations/20230203114114_create_messages.exs The "migration" actually creates the database table in our database.

6. Run the Ecto Migration (Create The Database Table)

In your terminal run the following command to create the messages table:

mix ecto.migrate

For context we recommend reading: hexdocs.pm/ecto_sql/Ecto.Migration.html

You should see the following in your terminal:

11:42:10.130 [info] == Running 20230203114114 Chat.Repo.Migrations.CreateMessages.change/0 forward

11:42:10.137 [info] create table messages

11:42:10.144 [info] == Migrated 20230203114114 in 0.0s

6.1 Review the Messages Table Schema

If you open your PostgreSQL GUI (e.g: pgadmin) you will see that the messages table has been created in the chat_dev database:

pgadmin-messages-table

You can view the table schema by "right-clicking" (ctrl + click on Mac) on the messages table and selecting "properties":

pgadmin-messages-schema-columns-view

Note: For sections 7, 8, and 9 we will be fleshing out how our code "handles" the different events that can occur in our chat app.

Phoenix abstracts away much of the underlying message-passing logic in Elixir's process communication (for more info on how Elixir processes communicate, read here).

In Phoenix, events/messages sent from the client are automatically routed to the corresponding handler functions based on the event name, making message handling seamless and straightforward!.

7. Insert Messages into Database

Open the lib/chat_web/channels/room_channel.ex file and inside the function def handle_in("shout", payload, socket) do add the following line:

Chat.Message.changeset(%Chat.Message{}, payload) |> Chat.Repo.insert

So that your function ends up looking like this:

def handle_in("shout", payload, socket) do
  Chat.Message.changeset(%Chat.Message{}, payload) |> Chat.Repo.insert  
  broadcast socket, "shout", payload
  {:noreply, socket}
end

If you noticed earlier, in our assets/js/app.js file, we used the function sendMessage() to push our message to the server on the "shout" event.

Phoenix routes the message to the server-side handle_in("shout", payload, socket) function because the event name matches 'shout'.

In this function, we handle the payload (which is the message text and any other data) and insert it into our database. Neat!

8. Load Existing Messages (When Someone Joins the Chat)

Open the lib/chat/message.ex file and import Ecto.Query:

defmodule Chat.Message do
  use Ecto.Schema
  import Ecto.Changeset
  import Ecto.Query # add Ecto.Query

Then add a new function to it:

def get_messages(limit \\ 20) do
  Chat.Message
  |> limit(^limit)
  |> order_by(desc: :inserted_at)
  |> Chat.Repo.all()
end

This function accepts a single parameter limit to only return a fixed/maximum number of records. It uses Ecto's all function to fetch all records from the database. Message is the name of the schema/table we want to get records for, and limit is the maximum number of records to fetch.

9. Send Existing Messages to the Client when they Join

In the /lib/chat_web/channels/room_channel.ex file create a new function:

@impl true
def handle_info(:after_join, socket) do
  Chat.Message.get_messages()
  |> Enum.reverse() # revers to display the latest message at the bottom of the page
  |> Enum.each(fn msg -> push(socket, "shout", %{
      name: msg.name,
      message: msg.message,
      inserted_at: msg.inserted_at,
    }) end)
  {:noreply, socket} # :noreply
end

and at the top of the file update the join function to the following:

def join("room:lobby", payload, socket) do
  if authorized?(payload) do
    send(self(), :after_join)
    {:ok, socket}
  else
    {:error, %{reason: "unauthorized"}}
  end
end

Note: like section 7, Phoenix knows to call this function when the server sends the internal message :after_join via the channel process.

Our join/3 function in lib/chat_web/channels/room_channel.ex sends that :after_join message to the channel process when the client successfully connects to the "room:lobby" topic.

10. Checkpoint: Our Chat App Saves Messages!! (Try it!)

Start the Phoenix server (if it is not already running):

mix phx.server

Note: it will take a few seconds to compile.

In your terminal, you should see:

[info] Running ChatWeb.Endpoint with cowboy 2.8.0 at 0.0.0.0:4000 (http)
[info] Access ChatWeb.Endpoint at http://localhost:4000

webpack is watching the files…

This tells us that our code compiled (as expected) and the Chat App is running on TCP Port 4000!

Open the Chat web app in two separate browser windows: http://localhost:4000 (if your machine only has one browser try using one "incognito" tab)

You should be able to send messages between the two browser windows: phoenix-chat-example-basic-cropped

Congratulations! You have a working (basic) Chat App written in Phoenix!

The chat (message) history is saved!

This means you can refresh the browser or join in a different browser and you will still see the history!

Testing our App (Automated Testing)

Automated testing is one of the best ways to ensure reliability in your web applications.

Note: If you are completely new to Automated Testing or "Test Driven Development" ("TDD"), we recommend reading/following the "basic" tutorial: github.com/dwyl/learn-tdd

Testing in Phoenix is fast (tests run in parallel!) and easy to get started! The ExUnit testing framework is built-in so there aren't an "decisions/debates" about which framework or style to use.

If you have never seen or written a test with ExUnit, don't fear, the syntax should be familiar if you have written any sort of automated test in the past.

11. Run the Default/Generated Tests

Whenever you create a new Phoenix app or add a new feature (like a channel), Phoenix generates a new test for you.

We run the tests using the mix test command:

........
Finished in 0.1 seconds (0.05s async, 0.06s sync)
8 tests, 0 failures

Randomized with seed 157426

In this case none of these tests fails. (8 tests, 0 failure)

12. Understanding The Channel Tests

It's worth taking a moment (or as long as you need!) to understand what is going on in the /room_channel_test.exs file. Open it if you have not already, read the test descriptions & code.

For a bit of context we recommend reading: https://hexdocs.pm/phoenix/testing_channels.html

12.1 Analyse a Test

Let's take a look at the first test in /test/chat_web/channels/room_channel_test.exs:

test "ping replies with status ok", %{socket: socket} do
  ref = push socket, "ping", %{"hello" => "there"}
  assert_reply ref, :ok, %{"hello" => "there"}
end

The test gets the socket from the setup function (on line 6 of the file) and assigns the result of calling the push function to a variable ref push merely pushes a message (the map %{"hello" => "there"}) on the socket to the "ping" topic.

The handle_in function clause which handles the "ping" topic:

def handle_in("ping", payload, socket) do
  {:reply, {:ok, payload}, socket}
end

Simply replies with the payload you send it, therefore in our test we can use the assert_reply Macro to assert that the ref is equal to :ok, %{"hello" => "there"}

Note: if you have questions or need any help understanding the other tests, please open an issue on GitHub we are happy to expand this further! (we are just trying to keep this tutorial reasonably "brief" so beginners are not "overwhelmed" by anything...)

13. What is Not Tested?

Often we can learn a lot about an application (or API) from reading the tests and seeing where the "gaps" in testing are.

Thankfully we can achieve this with only a couple of steps:

13.1 Add `excoveralls` as a (Development) Dependency to `mix.exs`

Open your mix.exs file and find the "deps" function:

defp deps do

Add a comma to the end of the last line, then add the following line to the end of the List:

{:excoveralls, "~> 0.15.2", only: [:test, :dev]} # tracking test coverage

Additionally, find the def project do section (towards the top of mix.exs) and add the following lines to the List:

test_coverage: [tool: ExCoveralls],
preferred_cli_env: [
  coveralls: :test,
  "coveralls.detail": :test,
  "coveralls.post": :test,
  "coveralls.html": :test
]

Then, install the dependency on excoveralls we just added to mix.exs:

mix deps.get

You should see:

Resolving Hex dependencies...
Dependency resolution completed:
* Getting excoveralls (Hex package)
... etc.

13.2 Create a New File Called `coveralls.json`

In the "root" (base directory) of the Chat project, create a new file called coveralls.json and copy-paste the following:

{
  "coverage_options": {
    "minimum_coverage": 100
  },
  "skip_files": [
    "test/",
    "lib/chat/application.ex",
    "lib/chat_web.ex",
    "lib/chat_web/telemetry.ex",
    "lib/chat_web/components/core_components.ex",
    "lib/chat_web/channels/user_socket.ex"
  ]
}

This file is quite basic, it instructs the coveralls app to require a minimum_coverage of 100% (i.e. everything is tested1) and to ignore the files in the test/ directory for coverage checking. We also ignore files such as application.ex, telemetry.ex, core_components.ex and user_socket.ex because they are not relevant for the functionality of our project.

1We believe that investing a little time up-front to write tests for all our code is worth it to have fewer bugs later. Bugs are expensive, tests are cheap and confidence/reliability is priceless.

13.3 Run the Tests with Coverage Checking

To run the tests with coverage, copy-paste the following command into your terminal:

MIX_ENV=test mix do coveralls.json

For windows use:

$env:MIX_ENV="test"; mix do coveralls.json

You should see:

Randomized with seed 527109
----------------
COV    FILE                                        LINES RELEVANT   MISSED
100.0% lib/chat.ex                                     9        0        0
100.0% lib/chat/message.ex                            26        4        0
100.0% lib/chat/repo.ex                                5        0        0
 70.0% lib/chat_web/channels/room_channel.ex          46       10        3
100.0% lib/chat_web/components/layouts.ex              5        0        0
100.0% lib/chat_web/controllers/error_html.ex         19        1        0
100.0% lib/chat_web/controllers/error_json.ex         15        1        0
100.0% lib/chat_web/controllers/page_controller        9        1        0
100.0% lib/chat_web/controllers/page_html.ex           5        0        0
100.0% lib/chat_web/endpoint.ex                       49        0        0
 66.7% lib/chat_web/router.ex                         27        3        1
[TOTAL]  80.0%
----------------

As we can se here, only 80% of lines of code in /lib are being "covered" by the tests we have written.

To view the coverage in a web browser run the following:

MIX_ENV=test mix coveralls.html ; open cover/excoveralls.html

This will open the Coverage Report (HTML) in your default Web Browser:

coverage-80-percent

13.4 Write a Test for the Untested Function

Open the test/chat_web/channels/room_channel_test.exs file and add the following test:

test ":after_join sends all existing messages", %{socket: socket} do
  # insert a new message to send in the :after_join
  payload = %{name: "Alex", message: "test"}
  Chat.Message.changeset(%Chat.Message{}, payload) |> Chat.Repo.insert()

  {:ok, _, socket2} = ChatWeb.UserSocket
    |> socket("person_id", %{some: :assign})
    |> subscribe_and_join(ChatWeb.RoomChannel, "room:lobby")

  assert socket2.join_ref != socket.join_ref
end

Finally, inside lib/chat_web/router.ex, comment the following piece of code.

  pipeline :api do
    plug :accepts, ["json"]
  end

Since we are not using this :api in this project, there is no need to test it.

Now when you run MIX_ENV=test mix do coveralls.json you should see:

Randomized with seed 15920
----------------
COV    FILE                                        LINES RELEVANT   MISSED
100.0% lib/chat.ex                                     9        0        0
100.0% lib/chat/message.ex                            26        4        0
100.0% lib/chat/repo.ex                                5        0        0
100.0% lib/chat_web/channels/room_channel.ex          46       10        0
100.0% lib/chat_web/components/layouts.ex              5        0        0
100.0% lib/chat_web/controllers/error_html.ex         19        1        0
100.0% lib/chat_web/controllers/error_json.ex         15        1        0
100.0% lib/chat_web/controllers/page_controller        9        1        0
100.0% lib/chat_web/controllers/page_html.ex           5        0        0
100.0% lib/chat_web/endpoint.ex                       49        0        0
100.0% lib/chat_web/router.ex                         27        2        0
[TOTAL] 100.0%
----------------

This test just creates a message before the subscribe_and_join so there is a message in the database to send out to any clien that joins the chat.

That way the :after_join has at least one message and the Enum.each will be invoked at least once.

With that our app is fully tested!

Authentication

We can extend this project to support basic authentication. If you want to understand how Authentication is implemented the easy/fast way, see: auth.md

Adding `Presence` to track who's online

One of the great advantages of using Phoenix is that you can easily track processes and channels.

This paves the way to effortlessly showing who's online or not!

If you are interested in developing this feature, we have created a guide in presence.md just for you! 😀

Continuous Integration

Continuous integration lets you automate running the tests to check/confirm that your app is working as expected (before deploying). This prevents accidentally "breaking" your app.

Thankfully the steps are quite simple.

For an example ci.yml, see:

.github/workflows/ci.yml

Deployment!

Deployment to Fly.io takes a couple of minutes, we recommend following the official guide: fly.io/docs/elixir/getting-started

Once you have deployed you will will be able to view/use your app in any Web/Mobile Browser.

e.g: phoenix-chat.fly.dev/

thats-all-folks

What Next?

If you found this example useful, please ⭐️ the GitHub repository so we (and others) know you liked it!

If you want to learn more Phoenix and the magic of LiveView, consider reading our beginner's tutorial: github.com/dwyl/phoenix-liveview-counter-tutorial

For a version of a chat application using LiveView you can read the following repository: github.com/dwyl/phoenix-liveview-chat-example

Thank you for learning with us! ☀️

Inspiration

This repo is inspired by @chrismccord's Simple Chat Example: https://github.com/chrismccord/phoenix_chat_example ❤️

At the time of writing Chris' example was last updated on 20 Feb 2018 and uses Phoenix 1.3 see: issues/40. There are quite a few differences (breaking changes) between Phoenix 1.3 and 1.6 (the latest version).

Our tutorial uses Phoenix 1.6.2 (latest as of October 2021). Our hope is that by writing (and maintaining) a step-by-step beginner focussed tutorial we contribute to the Elixir/Phoenix community without piling up PRs on Chris's repo.

Awesome

Phoenix Chat Example

Why?

What?

Who?

How?

0. Pre-requisites (Before you Start)

Check You Have Everything Before Starting

First Run the Finished App

Clone the Project:

Install the Dependencies

Run the App

1. Create The App

Run the Tests

2. Create the (WebSocket) "Channel"

3. Update the Template File (UI)

3.1 Update Layout Template

3.2 Update the page_controller_test.exs

4. Update the "Client" code in App.js

4.1 Comment Out Lines in user_socket.js

Storing Chat Message Data/History

5. Generate Database Schema to Store Chat History

6. Run the Ecto Migration (Create The Database Table)

6.1 Review the Messages Table Schema

7. Insert Messages into Database

8. Load Existing Messages (When Someone Joins the Chat)

9. Send Existing Messages to the Client when they Join

10. Checkpoint: Our Chat App Saves Messages!! (Try it!)

Testing our App (Automated Testing)

11. Run the Default/Generated Tests

12. Understanding The Channel Tests

12.1 Analyse a Test

13. What is Not Tested?

13.1 Add excoveralls as a (Development) Dependency to mix.exs

13.2 Create a New File Called coveralls.json

13.3 Run the Tests with Coverage Checking

13.4 Write a Test for the Untested Function

Authentication

Adding Presence to track who's online

Continuous Integration

Deployment!

What Next?

Inspiration

Recommended Reading / Learning

3.2 Update the `page_controller_test.exs`

4.1 Comment Out Lines in `user_socket.js`

13.1 Add `excoveralls` as a (Development) Dependency to `mix.exs`

13.2 Create a New File Called `coveralls.json`

Adding `Presence` to track who's online