TDD Phoenix Update (Nov 2020)

Since my last update, I’ve tried to do two major things: improve the overall legibility and revisit all the book’s technical content.

I was also a guest in episode 18 of the Thinking Elixir podcast. So if you want to hear me talk a bit about the book, give it a listen.

This update includes all of the following, so feel free to skip to a particular section or read it all. I promise it’s not that long.

• Improved legibility
• Revisiting all technical content
• The road to v1
• What about LiveView?
• Comments, suggestions, and testimonials

Improved legibility

I want TDD Phoenix to be a technical book that is enjoyable to read. That requires better typesetting and polished writing. So I tried improving both.

I removed the top-level header with the book name in every chapter, and I moved the work-in-progress banner to the bottom of the page. Now you can dive straight into the content without extra headers getting in your way.

Before

After

I have revised every chapter to improve the flow, updating subheaders, making the writing tighter, and (of course) fixing typos. The latter chapters needed more improvement since they had received fewer revisions, but all chapters benefited from modifications.

Finally, I added a short conclusion to send the reader off with encouragement to practice.

Revisiting all technical content

The most significant change was rewriting the entire application with Elixir 1.11, Phoenix 1.5, and Erlang 23.0. I rebuilt the application — following the book myself — and updated the code samples to reflect output differences.

Doing so brought light to parts of the book that could be improved or simplified. Some of them I fixed. Others I plan to fix soon.

For example, the Creating Users chapter had a complicated refactoring solely because I used a @conn struct (instead of a @changeset) when first rendering the user creation form. It is not difficult to do the refactor, but my explanation was convoluted and took more space than was merited. So I just used a @changeset from the beginning and made it simpler.

I also updated the book to use Wallaby 0.26.2, but here I only did a partial update. The newer versions of Wallaby use Chromedriver (which we now use in the book) but it also introduced an optional Wallaby.Feature module and a feature macro. Since they’re optional, I didn’t include them in this update. But I intend to use them in the future.

Unfortunately, the move to Chromedriver did not come without trade-offs. Wallaby used to use a pool of phantomjs instances. Now, it only uses one Chromedriver instance. Sometimes that results in a strange HTTPoison error because it seems like connections to Chromedriver are failing:

** (RuntimeError) Wallaby had an internal issue with HTTPoison:
%HTTPoison.Error{id: nil, reason: :checkout_timeout}
%HTTPoison.Error{id: nil, reason: :econnrefused}
%HTTPoison.Error{id: nil, reason: :closed}

There’s a long discussion in Wallaby’s GitHub issues, and I believe people are working on a permanent solution. For now, if you run into that issue, you can run mix test --trace or mix test --max-cases 1 which will remove parallelism from your test suite and allow Chromedriver to work properly.

The road to v1

Writing never ends. But I’d like to have a goal for the first version of the book. So, this is my current plan:

• Updating Wallaby syntax to use feature macro.
• Improve channel testing. In the Adding History to Chat Rooms chapter, we refactor the creation of messages to be asynchronous. I am not pleased with how channel testing ends because it can cause Ecto errors even though the tests pass. That happens when the test process terminates successfully — taking with it the database connection — but the ChatChannel hasn’t finished inserting a new message.
• Use mix phx.gen.auth for authentication
• Of course, rereading and updating writing and application code.
• Improving the design of the website and making pdf, epub, and mobi versions available.

What about LiveView?

Several people have asked me if I plan to include LiveView in the book. The answer is yes, but not on version 1. I think version 2 will be largely about adding LiveView.

LiveView presents a different set of tools to test our application, and I would like to do it justice. Covering it well requires adding a lot of content or replacing a lot of the content we already have. So I’ve decided to draw the line there, and I aim to include it in version 2.

If you are interested in testing LiveView now, I am creating a separate course that aims to cover as much of testing LiveView as possible. You can find that at testingliveview.com.

Comments, suggestions, and testimonials

Finally, if you’d like to say something nice about the book and have me include it on the home page as a testimonial, I’d love to do that. Testimonials can be very helpful for those considering reading the book for the first time.

And if you have comments or suggestions, I’d love to hear what could be improved. I am always eager to hear from readers. So, please send me an email, and let’s get a conversation started.