ndreynolds.com https://ndreynolds.com Tue, 05 Feb 2019 00:00:00 UT Learning Haskell via Advent of Code https://ndreynolds.com/posts/2019-02-05-learning-haskell-via-advent-of-code.html My Goblins and Elves do battle in Day 15

Inspired by this post from Forest Smith on his experience learning Rust with Advent of Code, I wanted to share my own experience working through the problems this past December to improve my Haskell skills.

Advent of Code

Advent of Code (AoC) is a collection of holiday-themed programming puzzles structured as an Advent calendar—one puzzle is released each day at midnight from December 1st until the 25th. The puzzles are a bit reminiscent of the Project Euler problems, but with less math and more fun. The great thing about AoC is that there’s something for everyone. For those who like competitive programming, there’s a leaderboard tracking the 100 fastest users to solve each day’s puzzle. Others don’t compete, but just enjoy solving the puzzles or use them to learn something new.

I decided to use the puzzles as an opportunity to learn some more Haskell. Haskell and I have had an off-and-on relationship the last several years. The first time I tried it (in 2014), my mind was blown by functional programming, pattern matching, type theory, and particularly Cabal “dependency hell”—the circle of hell that Dante must have forgotten about. Even back then, a part of me really liked Haskell, but I was just in over my head.

Since then, Elixir has been my gateway drug into real world FP, and I can feel a lot of Haskell concepts starting to really click in my mind. Also, improvements to Cabal and new tools like Stack have made the experience smoother for Haskell beginners.

My Experience with Haskell

All of my solutions can be found in my repository on GitHub. Towards the end, my holiday travels got in the way, so I only managed 18 of the 25 puzzles, but I’m still quite proud of that.At first, I was so motivated that I wanted to do them all in Racket, too, but that proved a bit too ambitious. I think I’ll try Racket next year.

Structuring Solutions

I spend so much time fiddling with build tools and manifests at work that I find it really satisfying to just pass a program directly to the compiler.

I decided to write each day’s solution (usually two parts) as a single DayN.hs file that I’d run with runhaskell or compile with ghc. I generally stuck to what’s included in the GHC distribution (mostly base and containers) so that the programs were free of additional dependencies. (I made a few exceptions that I’ll mention later.)

Working with I/O

The AoC puzzles have a personalized input file that you need to download and run against your program. In addition to the input file, there is usually a simplified example to check the results of your algorithm against. It’s a good fit for the Unix philosophy of having programs exchange data via the standard streams, as I could just redirect different files to the program’s stdin, as well as use pipes for some light preprocessing. So most of the programs are run like this:

Haskell’s Prelude provides a very elegant abstraction around the processing of standard IO streams: interact :: (String -> String) -> IO () (docs). You just provide a function that accepts stdin as a String and returns another String to be written to stdout, and it handles the rest. I used variations of this pattern in most solutions:

Parsing Input: To regex or not to regex

The different puzzles called for different approaches to parsing input. Some of the inputs were simple enough that lines and a little transformation did the job, whereas others called for a regular expression or a real parser. (Sometimes the parsing was even the biggest challenge.)

Many in the Haskell community tend to prefer parser combinators like Parsec and its derivatives for jobs that programmers in other languages would use a regular expression for. One sign of this (or maybe the reason) is that you’ll find Parsec bundled with GHC, but not any regex libraries.

I actually quite like regexps (short ones, anyway) and I think they can be the right tool for a lot of jobs. For example, Day 10 required parsing position and velocity pairs from the following input:

position=<-50310,  10306> velocity=< 5, -1>
position=<-20029,  -9902> velocity=< 2,  1>
position=< 10277, -30099> velocity=<-1,  3>

Regular expressions are particularly handy for extracting numbers from text with a lot of extraneous information and whitespace you don’t care about.

So I figured out how to use them in Haskell, which is a bit of a challenge itself. I actually went in a different direction than the linked post and used Text.Regex.TDFA, which is a new, pure Haskell regex engine.

In other cases, using parser combinators really was the right approach. For example, in Day 4, my task was to sneak into Santa’s prototype suit manufacturing lab, which involved parsing the “event log” of different elf guards as they’d start their shifts, fall asleep, wake up, and so on:

[1518-11-20 23:58] Guard #1229 begins shift
[1518-11-21 00:51] falls asleep
[1518-11-21 00:53] wakes up
[1518-11-21 00:57] falls asleep
[1518-11-21 00:59] wakes up
[1518-11-22 00:00] Guard #2441 begins shift
[1518-11-22 00:12] falls asleep
[1518-11-22 00:13] wakes up
[1518-11-22 00:17] falls asleep
[1518-11-22 00:46] wakes up
[1518-11-22 00:52] falls asleep
[1518-11-22 00:54] wakes up

I’m not saying you couldn’t solve this with a regex, but the fact that each guard can take an arbitrary number of naps would make it very ugly. So I went with Megaparsec, which I’d already used in another project. It’s more or less the same API as Parsec, but includes some fixes and enhancements that make it a bit nicer to work with. So far it’s been a real pleasure to use.

To parse the event log, I cobbled together the following:

While the whitespace handling is a bit sloppy here, it has some nice properties. It’s not possible to parse an Awake event followed by another Awake event. Parser combinators make it very easy to express a particular order that must be followed.

Profiling Slow Code

Most of the puzzles have two parts. It’s common to be able to brute force the solution to Part 1, but to need to step back and think about how to more efficiently solve Part 2. It’s a little bit like this:

  • Part 1: Compute factorial(n).
  • Part 2: Compute factorial(n1000).

In other cases, my initial solution was just plain slow because I’d used the wrong data structures or missed a critical bottleneck. For these cases, I used GHC’s built-in profiling tools.

GHC provides two particularly useful profiling options:

  • -prof - Compiles for cost-center profiling. This means profiling is turned on, but adding this alone doesn’t define any cost centers. Cost centers are just program annotations that flag a particular expression for profiling. They can be added manually with {-# SCC myId #-}.
  • -fprof-auto - This option automatically gives all bindings SCC annotations (with the exception of those referenced by an INLINE pragma), so you don’t need to add any manually.

At this point, we can compile a program for profiling, but we still need to tell the runtime system (RTS) to generate the profile when the program is ran. This can be done (among other ways), via command-line arguments:

  • +RTS - Demarcates the beginning of the RTS options (which are removed from the argv given to your program). Ended with -RTS or automatically when the end of arguments is reached.
  • -p - RTS option that produces a time profile (i.e. where is the program spending its time?).
  • -h - RTS option that produces a heap profile (i.e. memory usage).

My Day 15 solution (source), which produced the GIF at the top of the post, was initially horribly slow.

The puzzle involves creating a simulation of a battle between an army of elves and an army of goblins in true dungeon crawler style. Each unit on the map has a sort of deterministic AI. Units each have turns in a pre-defined series, and each turn they can either attack an enemy in range, or move one square towards the nearest enemy. Finding the nearest enemy is definitely the tough part.

Units cannot move through walls (they’re fighting in a cave) and they cannot move through each other—so the simulation requires finding, for each unit, the shortest path to an enemy.In the event of multiple shortest paths to an enemy, the directions specify that the next enemy in reading order (i.e., left-to-right, then top-to-bottom) is chosen. This all means calculating the paths in each round is O(n2), as we have to calculate the paths between all units in order to find the shortest ones.

From the puzzle directions:

Targets:      In range:     Reachable:    Nearest:      Chosen:
#######       #######       #######       #######       #######
#E..G.#       #E.?G?#       #E.@G.#       #E.!G.#       #E.+G.#
#...#.#  -->  #.?.#?#  -->  #.@.#.#  -->  #.!.#.#  -->  #...#.#
#.G.#G#       #?G?#G#       #@G@#G#       #!G.#G#       #.G.#G#
#######       #######       #######       #######       #######

In order to find the shortest paths, I used Dijkstra’s algorithm. My implementation was correct on small sample inputs, but was too slow to run on my real input. I knew something was wrong, so I used the profiler to see what my program was up to:

Running the second line generates a Day15.prof file in the current directory.

By inspecting the report, I found the problem. Dijkstra’s algorithm works by keeping a set of unvisited neighbor nodes and visiting these in order by shortest distance. I had actually used Data.Set to store these unvisited neighbors and was using minimumBy to find the next one to visit. Unsurprisingly, this was a very hot code path, and my program was spending 99% of its time there.

A priority queue makes this operation efficient. Elements of the queue are ranked by their priority—here, by their distance. I used the Data.PSQueue implementation, which supports O(1) retrieval of the element with the lowest priority, as well as O(log n) insertion, deletion and update operations.

My program now produces the following time profile, which is quite reasonable:

	Tue Feb  5 20:35 2019 Time and Allocation Profiling Report  (Final)

	   Day15 +RTS -p -hc -RTS

	total time  =       60.23 secs   (60231 ticks @ 1000 us, 1 processor)
	total alloc = 75,047,638,704 bytes  (excludes profiling overheads)

COST CENTRE              MODULE       SRC                               %time %alloc

lookup                   Data.PSQueue Data/PSQueue.hs:(117,1)-(125,37)   33.4   35.4
open                     Main         Day15.hs:127:1-55                  20.3    1.6
insert                   Data.PSQueue Data/PSQueue.hs:(139,1)-(149,49)   12.9   21.0
adjustWithKey            Data.PSQueue Data/PSQueue.hs:(190,1)-(198,62)   12.1   13.0
deleteMin                Data.PSQueue Data/PSQueue.hs:(317,1)-(318,43)    6.2    7.8
dijkstra.update          Main         Day15.hs:(115,3)-(121,31)           6.1    5.9
dijkstra.prune           Main         Day15.hs:(108,3)-(113,33)           1.6    4.2
adjacents                Main         Day15.hs:139:1-67                   1.3    2.2
dijkstra.prune.neighbors Main         Day15.hs:112:5-78                   1.1    2.2
openAdjacents            Main         Day15.hs:142:1-61                   1.1    2.0
dijkstra.initQ           Main         Day15.hs:(99,3)-(100,78)            0.5    1.8

The only red flag is the 60.23 sec it takes to run! I expected some overhead, but not quite so much. Compiling again without the profiling options and with -O2 brings the total runtime down to a few seconds.

Pattern Matching

I learned from Elixir & Erlang how powerful pattern matching can be. Luckily Haskell gets us mostOne of the things I seem to miss the most is being able to match for equality of two values by using the same variable twice. For example, in Erlang the match expression {x, x} = {0, 0} succeeds, whereas {x, x} = {0, 1} does not (match error). In Haskell, given a similar (x, x) = (0, 0), the compiler complains about multiple declarations of x.

 of the way there and with types to boot.

In the puzzles, I often found it lovely to just transliterate the mapping in the puzzle directions to one in Haskell.

For example, Day 12 called for building a kind of single-row cellular automatonFor example, Conway’s Game of Life is a cellular automaton with a similarly defined rule-set.

 from an initial state with rules for whether each cell is occupied (alive) or unoccupied (dead) in the next generation:

initial state: #..#.#..##......###...###

...## => #
..#.. => #
.#... => #
.#.#. => #
.#.## => #
.##.. => #
.#### => #
#.#.# => #
#.### => #
##.#. => #
##.## => #
###.. => #
###.# => #
####. => #

The above rules only cover the “alive” cases; anything else is assumed dead in the next round. I was pretty happy with how this converted to Haskell, where I defined a function to advance a block of cells to the next generation based on the rules above:

Algebraic Data Types

Algebraic data types are wonderfully expressive for certain problems. I sorely miss them when working in dynamic languages.

For example, on Day 13, which involved building an ASCII rail network, I used the ADTs to capture all the possible states my tracks could be in:

It was then very helpful to have the compiler’s help in making sure I’d handled all the possible values of union types—for example, every track type above in the logic to move a cart.

I think even more beneficial than type checking was how designing the types for each problem helped me to plan the solution before writing any real code. Thinking in terms of types makes it possible to start at the very top and drill your way down.

In the Day 13 puzzle, the objective for the first part was—given a number of carts hurtling down the tracks, eventually right at one another—to find the first cart crash. A simple network of tracks looks like this:

   x axis ->

y  /->-\
|  |   |  /----\
v  | /-+--+-\  |
   | | |  | v  |
   \-+-/  \-+--/
     \------/

So I started there with the assumption that I’d need a type for the entire network of tracks, and a type for the coordinate pair where the crash occurs:

This then led to the definition of the track network as a map of coordinates to tracks:

Then I compiled all the information about tracks from the description into the track type. In order to package everything up together—the track direction and whatever’s on top of it—I decided to also store the carts with the tracks themselves:

From here, I continued with carts, which travel in a particular direction and the cycling intersection rule that tells the carts which way to turn.

By starting with the types, I had a solid foundation to write the logic to parse the tracks and simulate the cart travel. This is something I’m definitely starting to miss in dynamic languages. There I can still plan the structure of nested data structures, but I can’t encode the rules into its definition in quite the same way.

Plotting Data with Gnuplot

For a few different puzzles, I found it useful to plot data generated by the program in order to visualize it.

There are a number of different Haskell libraries for creating charts that rely on different backends. For example, the Chart library is backed by Cairo and provides a number of different chart types and export formats.

After looking around, I settled on easyplot, which wraps the gnuplot command line utility. The package can generate .dat files with the plot data in the Gnuplot-supported format and can run the X11 viewer. For example, the following plots two points:

It’s also possible to pass functions:

Plots can also be rendered to PNG instead by swapping X11 for (PNG "sin.png"):

Gnuplot is ancient, so it doesn’t produce the prettiest charts, but I found it and its Haskell wrapper lovely for their simplicity. Without passing any options, they already produce something reasonable. This is great for trying to make sense of data without getting bogged down in the the details.

With the .dat file generated by the Haskell wrapper, gnuplot can also be ran directly, which allows for configuring plotting on the command line, e.g.:

Other programs can also render Gnuplot .dat files, so there’s a lot you can do with the data once it’s out of your Haskell program.

I used this strategy for Day 10, which involved finding a message formed by shooting stars as they align for a split second. I didn’t really know what to expect—I wasn’t sure if all the stars would cluster together or only some of them, so I decided to plot the coordinates when alignment reached a certain threshold and take a look. It worked pretty well:

In case you’re wondering, as I did for a long while, the message is upside down.

Here I used the gnuplot command above to squeeze the y-axis to make the letters readable.

Formatting Code

While it has nothing to do with puzzles, automatic code formatting has become an important part of my workflow.

This past year, I’ve been using Elixir’s mix format (inspired by tools like gofmt) to format all the Elixir code I write. I used to think aligning the code to make it “pretty” was my job, but now I’ve realized that’s a big waste of time.

Haskell doesn’t yet and may never have a canonical formatter included with GHC, but there are some different packages to fill this need.

I used brittany to format my solutions and was impressed with the results. I didn’t always agree with it’s choices, but I think that’s the trade-off when using a formatter.

]]> Tue, 05 Feb 2019 00:00:00 UT https://ndreynolds.com/posts/2019-02-05-learning-haskell-via-advent-of-code.html Nick Reynolds Building Terminal Apps with Elixir https://ndreynolds.com/posts/2019-01-27-terminal-apps-with-elixir.html

Elixir may seem like an odd choice for building terminal applications. In fact, when I started this project, that’s exactly what I thought.

Before I get into that, I’ll first give you some background as to why I even would try something like that, then I promise to get back to building terminal apps.

Connecting to remote Observer nodes

Where I work, we run our Elixir apps in production as Erlang OTP releases built with Distillery. The OTP releases run in Docker containers. The containers are now orchestrated with Kubernetes, but at the time we were using Rancher.

A little over a year ago, I desperately wanted to connect the Erlang ObserverIn case you haven’t used it, Observer is one of my favorite tools in the Erlang toolbox. I don’t know of any other VM that provides the same level of insight into the running system. Start it with :observer.start() in the IEx shell.

 to one of our production nodes. I was debugging some background jobs that we’d implemented via gen_server processes, and was confused by their behavior in production.

Observer is a GUI application built with wxWidgets, so while it runs on most platforms, you do need a desktop environment to run it. It’s also possible to connect it to remote Erlang nodes, including those running on headless servers.

Connecting Observer to a remote Erlang node is usually accomplished with SSH port forwarding to avoid needing to publicly expose your Erlang node.

Each server runs a program called epmd (Erlang Port Mapper Daemon) which acts as a name server (or, say, a phone book) for all the Erlang nodes running on the server. When an Erlang node starts up in distributed mode, it sends its name and port to epmd for registration. All of the currently registered names can be retrieved with epmd -names or from an Erlang shell with net_adm:names().

In the same way, Observer gets these names from epmd and displays them under the “Nodes” menu item. So the magic of SSH port forwarding here is that we can just trick Observer into think it’s talking to the local epmd.

First, on the remote server, get epmd’s port and the port of the node you’d like to connect to:

And now forward both of those ports to localhost:

Now the remote epmd and remote node are both listening locally, which allows Observer to connect to the remote epmd and node as if they were also running locally.

Containers unfortunately add a few more layers to this, as Docker and the container orchestrator both have their own networking layers complete with their own port mappers. For example, connecting to a container via its port requires mapping a host port to the container port and connecting via the host port.With Kubernetes, this is possible with the kubectl port-forward command. There’s even a nice script to automate it.

I tried for quite a while to thread my connection through all the layers in our container running under Rancher, but I was never able to get it working with dynamic ports.

An Erlang observer for the terminal

In my frustration, I started to ask why I can’t just run this thing in the terminal. I’m a big fan of the terminal top and htop utils for exactly this reason. They work everywhere: on my Mac, on my Linux machine, and on whatever random VM I happen to be ssh-ed into.

So I started to look around and I discovered etop, which comes bundled with Erlang:

iex> :etop.start()
========================================================================================
 nonode@nohost                                                             21:56:50
 Load:  cpu         0               Memory:  total       23976    binary         84
        procs      56                        processes    6879    code         7958
        runq        0                        atom          388    ets           598

Pid            Name or Initial Func    Time    Reds  Memory    MsgQ Current Function
----------------------------------------------------------------------------------------
<0.64.0>       group:server/3           '-'   34192  973332       0 group:server_loop/3
<0.111.0>      etop_txt:init/1          '-'    6970   42348       0 etop:update/1
<0.8.0>        erl_prim_loader          '-'    1161  196980       0 erl_prim_loader:loop
<0.62.0>       user_drv                 '-'    1109   13820       0 user_drv:server_loop
<0.48.0>       code_server              '-'     214  284652       0 code_server:loop/1
<0.113.0>      erlang:apply/2           '-'      31    2808       0 observer_backend:fla
<0.66.0>       kernel_refc              '-'      17    3192       0 gen_server:loop/7
<0.44.0>       application_master:i     '-'       2    4008       0 application_master:m
<0.61.0>       supervisor_bridge:us     '-'       2   13784       0 gen_server:loop/7
<0.65.0>       kernel_config:init/1     '-'       2    2820       0 gen_server:loop/7
========================================================================================

Erlang Top prints some basic system stats along with the top 10 processes (sorted by reductions by default). It’s a great tool for every BEAM user’s toolbox to get an overview of the system health before you start digging deeper with other tools.

But what I was still really searching for was a real application like Observer, only text-based. For example, I wanted to visualize the supervision tree, find a process in it, and kill it, just by moving my cursor and pressing a few keys.

So I set out to build my own text-based Observer.

Termbox and C and NIFs, Oh My!

I knew that in order to be able to scroll with the arrow keys or click with the mouse, I’d need to allow the application to capture keyboard and click events.

Then I realized fairly quickly that it’s not as easy as it sounds. While Elixir & Erlang provide the ability to get a line (IO.gets/1) or a number of bytes/characters (IO.getn/1) from stdin, this is always line-buffered, meaning they don’t receive anything until either the <enter> key or <ctrl-d> key is pressed.

The explanation for this is that the terminal runs in what’s called cooked mode by default, which pre-processes (cooks) input before giving it to the program. Programs that need to handle key presses (for example, editors like vi and emacs) work by switching to raw mode, which allows for polling for each individual event.

Since there’s no Erlang API for changing the mode, I realized I’d have to do it myself from C code, and I’d need some sort of Port or NIF for that to work.

Moreover, terminal applications control the terminal by sending it ANSI escape codes. These codes can vary by terminal and system, so applications typically use a database called terminfo to find correct control sequences for the current system.

Because this is all still pretty tedious, most applications use a library like curses or ncurses to do the heavy lifting, so they can focus on the application logic.

In my case, I’d already had my eye on an alternative called termbox, which aims to provide a more minimal API for controlling the terminal to write text-based user interfaces. Termbox treats the terminal as a grid of cells, and provides 12 main functions to manipulate it:

This minimal API is certainly much lighter than the ncurses API. On my machine, termbox.h is only 320 lines, while ncurses.h is 2094 lines. While that also means it’s missing some features, I figured a minimal API would be easier to build on top of, as I didn’t want to spend so much time working in C, and was more interested in building abstractions in Elixir.

So the next step was figuring out how to use it from Elixir. To do that, I created a library called ex_termbox that provides bindings to the termbox library as NIFs dynamically linked to the Erlang VM process.

NIFs aren’t always a good idea, as they make it very easy to crash the otherwise rock-solid VM with segfault errors, but if there’s no better alternative and it’s properly tested, I think using NIFs can make sense.

For the most part, the NIFs in ex_termbox are thin wrappers around the corresponding termbox function. For example, the NIF for retrieving the terminal width looks like this:

NIFs can receive Erlang terms as arguments and need to return Erlang terms. The erl_nif.h header declares functions and defines macros that help with converting to and from native types.

On the Elixir or Erlang side—when it comes to NIFs there’s no real difference—it’s necessary to load the native implementation (i.e., the shared lib) and define a stub implementation for each NIF:

With the bindings in place, the Elixir version works just like the C library.

The Imperative Mood

At this point, I thought I was done with yak shaving. It was time to write a terminal application.

But when I started to look at how real terminal applications are written, I realized that most terminal applications are written completely imperatively—i.e., as a step by step procedure for drawing the UI. For example, if you want to render a box, you start drawing lines in some kind of for-loop. Maybe later you package your box drawing logic as a procedure of its own, but its always up to the programmer to define the steps:

On the web, we’re lucky to have declarative languages like HTML and CSS. Take, for example, the definition of a simple HTML table:

I don’t have to tell the browser how to draw the table; it figures it out for me based on my declaration of the table’s structure. This is especially nice, because the browser will render the table differently based on the amount of screen real estate available for it.

Having worked a long time on web applications, I wasn’t willing to give up the benefits of declarative UIs. I wanted to build UIs in my terminal app the same way I build websites. I didn’t want my application logic to get lost in a sea of drawing commands, and I also didn’t want the imperative style that my termbox NIFs inherently have leak into my codebase.

A Terminal UI Kit for Elixir

Ratatouille is the other library I created on this adventure. It grew out of ex_termbox as a way to address this problem with views.

Ratatouille aims to define an HTML for the terminal and provide the rendering engine for it. Users can declare a UI and Ratatouille should figure out how to draw it to the screen. Because there’s no absolute positioning, the UI can be adapted to different terminal dimensions, and extended without the need to go through and update any pixel values.

Ratatouille’s HTML is implemented as an Elixir DSL:

That looks a lot like code, but it’s actually just a tree of elements, no different than what you could define with XML:

But because it’s defined in Elixir, the DSL simultaneously serves as a templating language, meaning it’s possible to mix in comprehensions, cases and conditionals:

The biggest challenge was (and still is) actually rendering the elements defined with the DSL. A rendering engine is in charge of both drawing and laying out content. Drawing is actually pretty easy once you have the layout.

Ratatouille renders content by reducing the element tree to a canvas of cells, and then later drawing the cells to the window in a single batch update.

The canvas is a struct which consists of a grid of cells (MxN) and a gradually gradually shrinking box representing the renderable region of the grid (the render box).

As an example, columns are rendered by dividing the render box horizontally and rendering each column’s children within that subdivision of the render box. Each of the resulting grids are then merged together to produce the complete grid.

(Actually) Writing Terminal Apps

As soon as the libraries were just barely working, I turned back to my original idea of a text-based Observer and started building it. It’s been a great way to test the libraries, as developing a real application tends to surface the bugs and guide the development towards what’s important.

The text-based Observer, which I’ve released as toby, aims to be (at least for now) a clone of the Observer GUI.

The Observer GUI is divided into 8 different tabs, so that’s where I started:

Observer’s tabs
Observer’s tabs
toby’s tabs
toby’s tabs

If you’ve ever created a computer game before, you’re probably familiar with a game loop. A game loop processes input, updates the game state, renders the game state to the screen, and then starts all over again.

I discovered that terminal apps can be built with a very similar loop. Toby started out like this:

This initial version of toby prototyped the application loop and the framework for tabs and switching between them. By pressing “p” on my keyboard, I can switch to the “Processes” tab. Then by pressing “a”, I can switch to the “Applications” tab. Only one tab is ever rendered at a time.

The pattern is simple but very powerful. The code spends the majority of its time in the loop/1 function and has the chance to process one event per loop. There’s no risk of losing events while we’re doing something else, as they’ll sit in the process mailbox (a FIFO queue) until we’re able to process them. After 1 second without an event, the loop is always restarted. This gives time-sensitive views a chance to update their content.

The state is stored in the recursion itself, by passing it (or an updated version) in any recursive calls. That’s actually the same way a gen_server works.

Rendering is just a business of writing functions that return views. I knew in the beginning from my experiences with React.js and Elm that “render” (or “view”) functions should be purely functional. If a render function always returns the same view for two calls with the same arguments, meaning it has no side-effects, it’s possible to do smart things. We can skip rendering if the arguments haven’t changed. When multiple render functions are called, we can parallelize them or render them out of order without affecting the final result.

In Elixir, there’s nothing to stop us from, say, reading and writing to ETS tables in render functions, so this is only a contract we strive to abide by.

Fetching Data

One important piece of the puzzle is missing from the last section. The first version of my application had only the current tab as application state. Moreover, we have a contract that render functions will never have side effects. So where does the data come from?

Experienced app developers know that you should never block the UI thread. Users expect to be able to interact with a system even when it’s busy making API requests or processing video. Otherwise they couldn’t cancel or abort these sorts of operations.

The same applies to the application loop. Rendering doesn’t just need to be pure, it has to be really fast. Similarly, handling an event also needs to be really fast so that the user can be given some kind of acknowledgment ASAP—even if it’s just a loading spinner.

For toby, which I someday hope to use in production, this is especially important. If you’re using Observer to debug a problem, chances are your system is already wounded. Retrieving information from a production system has to be done carefully so as to not overload it. I needed to make sure no amount of button mashing in my application would overload the BEAM.

It turns out Elixir has a great solution to this problem; we can spawn processes to do expensive things like loading data in the background. This is when I started to realize that Elixir is actually really great for writing apps.

In toby, I created a Data context to deal with the all things data-related:

lib/toby/data/
├── applications.ex
├── provider.ex
├── sampler.ex
└── server.ex

There’s Data.Server which acts as the public API and caching layer for retrieving statistics about the VM. It doesn’t mind being asked the same questions over and over again. Unless the cache entry is missing or expired (currently a 2 second expiry), it happily serves data directly from its cache (the gen_server state). This makes it possible to rapidly scroll through the processes list, as we only fetch the processes at most once every 2 seconds.

When the cache is expired or there’s no cache entry, requests are looked up with Data.Provider, which does all the expensive lookups. For toby, it’s currently fast enough to load everything within the scope of the GenServer.call/3 to the Data.Server process (most calls take microseconds), but in other apps this approach could be adapted to keep the cache warm or to request data asynchronously.

To display charts and other historical views, the server also maintains a circular buffer of system “samples” from Data.Sampler. Because sampling is done by the Data.Server

Scaling Application State

If render functions are pure, everything that we want to render has to live in the application loop’s state. For toby, that meant that the individual state for each tab had to be stored altogether in a big map. Without introducing new loops, there’s no real way around this.

Bundling everything together in one big loop has its pros and cons. One big map of state is easy to understand, but can look messy. Handling all the events for all the tabs in one place also starts to get a little out of control.

I played for a long time with different ways of combatting this. I experimented with React-style components, which each have their own state and event handlers. I didn’t want to run unnecessary processes to actually give them local state, so I faked it by having the application loop hold onto the component state and pass it component callbacks like render/1 and handle_event/2.

But my component solution started to feel a bit wrong in a functional language like Elixir. In React, you can arbitrarily nest component state and event handling. I realized that it works because React components map to the Document Object Model. They’re objects. Objects can store state and trigger events. Events on objects can have complex delegation (e.g. bubbling) logic.

Components are objects!

components = local state + methods

local state + methods = objects

https://twitter.com/czaplic/status/903266544544878592

With some inspiration from Elm Architecture, I decided to embrace the application loop and built a small runtime around it.

Now the application just defines model, update, and render functions, and the runtime handles wiring everything up. In the future, it’ll make it possible to add things like state snapshots or even a time-traveling debugger.

You can find the current definition of the toby application here:

https://github.com/ndreynolds/toby/blob/master/lib/toby/app.ex

There’s still a lot of work to do on toby and the supporting libraries. I intend for Ratatouille to be useful for all sorts of applications.

So that’s how I got started writing terminal apps in Elixir.

It’s been a lot of work so far, but the results have been promising. I really think Elixir is a great choice for building all sorts of applications.

Erlang makes concurrency easy, Elixir’s macros make it possible to write expressive DSLs, and both provide a nice functional framework that encourages simplicity and reduces bugs while remaining pragmatic enough to get things done.

]]> Sun, 27 Jan 2019 00:00:00 UT https://ndreynolds.com/posts/2019-01-27-terminal-apps-with-elixir.html Nick Reynolds Rust: First Impressions https://ndreynolds.com/posts/2015-02-10-rust-first-impressions.html I recently decided to give the Rust programming language a try. Although Rust had crossed my radar a few times before, I’d never gotten much further than Hello World!. The language has undergone a lot of change over the last few years, but things appear to finally be slowing down for its upcoming 1.0 release.

The Project

My latest encounter with Rust began when I set out to write a ray tracer to get some experience with graphics programming. I initially considered a few different languages.

As a GitHub search for “raytracer” shows, the typical language for the job is C++. And I think it makes sense. You have to recursively trace about a million rays of light through the scene, so you need something fast (or a book to read while you wait for your Ruby ray tracer to finish executing). It’s also a problem that maps well to the OOP paradigm. The “scene” will naturally have different sorts of shapes (e.g., planes, spheres, cubes), each with a mix of shared and unique behavior that can be modeled well with inheritance. Finally, bindings to a decent graphics library are a must, which C++ also accommodates.

It turns out that Rust also nicely meets these requirements. It’s fast, more or less supports OOP via its trait system, and has at least one nice graphics library. So I gave it a try. What follows are my impressions of the language as a Rust novice (so take my praises and criticisms with a grain of salt).

The Good

I had a pretty great experience with Rust, so there was a lot to like.

Ownership

Ownership is probably the most unique of Rust’s features. It’s also what I struggled the most with when it came to getting my code to compile.

The idea is that since Rust code isn’t garbage collected, and the programmer isn’t managing memory, the compiler needs some way to keep track of the lifetime of your data so that it can allocate and deallocate memory for you. In theory, this is awesome. You get the performance benefits of managing your own memory with all the safety of a garbage collected language.

In order for that to work, the compiler enforces a set of rules for ownership and borrowing of pointers and other resources. Resources are said to be owned by their variables. They can be borrowed by another variable, but just like a bike you lend out, the owner can’t use it while it’s being borrowed.

It does get a bit complicated and I’m not yet experienced enough to describe it in more detail, but I’m really liking the ownership system so far. I’ll qualify that by saying, given the choice between manually managing my memory or letting Rust do it, I’d choose Rust. Comparing Rust to a GC-ed language isn’t quite fair, as Rust is presumably being used because GC isn’t an option.

While the “borrow checker” has been the biggest hindrance in getting my Rust code to compile, it (theoretically) protects you from a whole class of memory issues (like leaks and dangling pointers). Based on my experience so far, I do think fighting the borrow checker is vastly preferable to hunting down the cause of a segfault in a large C/C++ codebase.

Cargo

Cargo, Rust’s package manager, has been a pleasure to work with. The best kind of package managers are the ones that just work, and so far that’s been for me with Cargo. The tool is reminiscent in many ways of Ruby’s Bundler, and it turned out that wasn’t a coincidence as both were created by the same people.

Cargo is similar to Bundler in that it provides a simple way to list out your build dependencies—each from either crates.io (the rubygems.org equivalent), a GitHub repo, or from the local filesystem. It then retrieves and builds your dependencies, saving the version numbers or git commit SHAs in the Cargo.lock file. With that file checked in to source control, it’s easy to get repeatable builds using exactly those same dependencies, so you don’t suffer from issues with others trying to build your project with slightly different versions of the dependencies. Pretty neat.

Cargo.toml

[dependencies.image]
git = "https://github.com/PistonDevelopers/image"

Cargo.lock

[[package]]
name = "image"
version = "0.2.0-alpha.10"
source = "git+https://github.com/PistonDevelopers/image#5b589d98e53da920a28dbed8b3ea83452280cdd2"
dependencies = [
 "num 0.1.12 (git+https://github.com/rust-lang/num)",
]

Support for Testing

Rust has some really cool built-in support for unit testing. This is great because every roadblock to writing tests makes them that much less likely to get written. In Rust, tests can be tagged with a #[test] attribute and added directly to the source file:

Once you’ve set up your project with Cargo, tests are easy to run:

Safety vs. Flexibility

Every language seems to make its own trade-offs between safety (protecting the programmer from him or herself) and flexibility (which allows you to do useful things). The protections that prevent you from unsafe memory access or type errors always come at the cost of some flexibility.

With C, you’re free to do whatever you want to your bits. If GCC doesn’t like the types you’ve assigned, you can always cast your way out of it—future segmentation faults notwithstanding. Haskell is on the other end of the spectrum. Its rigid type system protects you from all sorts of silly mistakes, but its functional purity makes normally simple things like printing to stdout or getting a random number considerably more difficult.

Rust seems to aim for somewhere in the middle of the two extremes. I think one of the clear goals of Rust is to provide a safer choice for the sort of systems programming that C or C++ is typically used for. One way to achieve safety is to prevent the programmer from doing anything useful, but I don’t think that’s the case here.

Rust encourages safety by providing reasonable defaults, but there’s usually an escape hatch if you need to do something not-so-safe (which can happen every now and then in the real world). By default, variable bindings are immutable, which means any mutation must be made explicit.

Rust also forgoes null pointers and encourages an Option type (similar to Swift’s optional and Haskell’s Maybe monad) to represent a value that may be absent. In languages like Java, null pointers often mean null pointer exceptions. With an optional type, the compiler can enforce that you handle both scenarios (i.e., value presence and absence). In my project, one example of this was checking for an intersection when tracing a ray. An intersection only occurs if there’s an object in the ray’s traced path, so it may be absent:

The Bad

There were a few things I didn’t like about Rust. I’m sure most of these are just due to my inexperience with the language or Rust being a relatively new language.

Unstable APIs

Rust is still in alpha and much of the standard API is currently marked as unstable. This means that—for now at least—every time you upgrade to the latest nightly, there’s a pretty good chance that your code will no longer compile. I’ve gone through this a few times with my ray tracer and spent a few hours moving to new APIs each time (for example, serialize to rustc-serialize). The other issue this presents is that a lot of the 3rd-party tutorials and example code out there won’t compile with the latest compiler.

The good news is that this is supposed to change soon with the 1.0 release.

Steep Learning Curve

One of the trade-offs made in exchange for all the nice things about Rust is that it takes a while to get off the ground. For me at least, it’s not a language like Python or Ruby that you can start making useful things with on your first day. Using Rust effectively is predicated on having a good understanding of the language. As a beginner, I struggled with compiler error messages that seemed cryptic taken out of context (mostly due to borrowing or ownership problems), but once I’d read more of the official book, they did start to make more sense. Moreover, like Haskell, Rust has a powerful type system and gives you a lot of rope to hang yourself with. I got stuck a few times when trying to define and deserialize a polymorphic “shape” type.

Lifetime Syntax

I think Rust generally has pretty nice syntax. I like its Ruby-style closures (|x| x * x). While I like the ownership paradigm, I’m not sold on the syntax for defining lifetimes. The terse a, b, c identifiers combined with the borrowed and mutable symbols can start to feel like reading and writing hieroglyphics:

Sure, I imagine this will get easier to read with time, but I wouldn’t mind some Java-style verbosity here.

Wrapping Up

I was going to add a “The Ugly” section to complete the trifecta, but my experience with Rust has actually been a really pleasant one. I’m sure the API stability and documentation will only improve with time.

With that said, I don’t think Rust is a good general purpose programming language. I don’t plan to use Rust for web programming any time soon. When it comes to rapid development, I think the extra cognitive overhead in dealing with ownership and complexities like String vs. &str make it hard sell against something like Ruby. But for problems in Rust’s wheelhouse—like system tools or operating systems or media decoders—where you need speed and safety, it’s a really great tool to have.

]]> Tue, 10 Feb 2015 00:00:00 UT https://ndreynolds.com/posts/2015-02-10-rust-first-impressions.html Nick Reynolds Getting AngularJS and Rails talking https://ndreynolds.com/posts/2015-01-31-getting-angular-and-rails-talking.html In this post, I want to explore a few of the ways to exchange data between a Rails app and an AngularJS module—looking at the pros and cons of each approach. While Angular sees a lot of usage in single-page applications (SPAs), I’ve found it just as useful for enhancing certain pages of a Rails application with more dynamic interfaces, while sticking to plain, scaffoldable CRUD screens for the rest of the app.

With this approach, it doesn’t make sense to kick HAML to the curb, turn your Rails app into a JSON API, and render everything on the client side. Rails may not be the new kid on the block anymore, but it has a lot of mature gems that make putting together a complex site a breeze.

With that in mind, it’s not always clear how best to combine the two technologies:

  • When do you use Angular templates and when do you stick with HAML/ERB?
  • How do you pass the data from the Rails side to your Angular controllers?

JSON endpoints in the Rails controller

The first approach is to provide a JSON format for the resource in your controller. Imagine we wanted to implement client-side filtering of a short list of items in a store’s inventory. We can easily add a JSON format to the index action:

Then from our HAML template, we’ll provide the Angular templating to dynamically render the items:

# app/views/items/index.html.haml
%input(type="text" ng-model="search")

%table(ng-controller="ItemsController")
  %thead
    %tr
      %th Name
      %th Price
  %tbody
    %tr(ng-repeat="item in items | filter : search")
      %td {{ item.name }}
      %td {{ item.price | currency }}

Lastly, we’ll initialize the scope’s items array by requesting the data as JSON from the Rails server using the $http service.

I like this approach, but it has a few issues:

  • The items are requested in an additional HTTP request and we’re only handling the success case. We’ve introduced the possibility that the second request fails and the user sees an empty list of items. In a production app, we’d have to add error-handling for that case, which comes with some added complexity.
  • It’s not always practical to create ad-hoc JSON routes for backend data. In this case, as items is clearly a collection of resources, it works well. If it were a list of filter options, adding a new JSON route becomes a little questionable.

ngInit (and ngInitial)

When building forms, it’s common to want to show or hide an option or when something else is selected. Say our inventory app collects some basic information about how the item is taxed when an item is added. If the item is marked as taxable, the “tax rate” field should appear. If it is not taxable, the field should be hidden.

The is definitely a job for Angular, but I’m not willing to give up simple_form in the process. Let’s see if we can make them play together.

The item form partial will be used for both the new and edit actions. The show/hide behavior must work for both a new item as well as for an existing item that has already been marked as taxable.

The ngInit directive evaluates an expression in the current scope. After assigning the taxable checkbox to the $scope.taxable via ng-model, we can use ng-init it to set its initial value:

# app/views/items/_form.html.haml
%div(ng-controller="ItemFormController")
  = simple_form_for @item do |f|
    = f.input :taxable, 'ng-model' => 'taxable', 'ng-init' => "taxable = #{@item.taxable.to_json}"
    = f.input :tax_rate, 'ng-if' => 'taxable'

Then from the Angular controller, there’s not much left to do:

While this a decent strategy for simple use cases like above, it’s easy to abuse and mixing Ruby and Angular templates can get ugly. A slightly cleaner approach is to use something like the ngInitial directive from this StackOverflow answer. This directive sets the initial value of the $scope variable using the value attribute, which will be set automatically by the form helper. I’ve slightly modified the directive below to also handle checkbox inputs:

It can then be used in the above HAML view like so:

# app/views/items/_form.html.haml
%div(ng-controller="ItemFormController")
  = simple_form_for @item do |f|
    = f.input :taxable, input_html: { 'ng-model' => 'taxable', 'ng-initial' => '' }
    = f.input :tax_rate, input_html: { 'ng-if' => 'taxable' }

(Unfortunately, I don’t know of a cleaner way to define valueless attributes.)

Using script tags

When mixing Backbone.js and Rails, it’s common to bootstrap Backbone models and collections from a script tag at the bottom of the page. It’s possible to do something similar in Angular by putting the data somewhere in the global scope and accessing it from the Angular controller.

# app/views/items/index.html.haml
:javascript
  window.items = #{@items.to_json};

While this is a bit simpler than requesting the data with the $http service and does work quite well, using global variables means the angular app loses its nice encapsulation, which can make testing problematic. Global variables also of course come with problems of their own.

JSON data attributes

Another approach is to render the data as JSON to data attributes. By adding a data-items attribute to the element with the ng-controller attribute, you can easily access the data with an injected $element dependency.

# app/views/items/index.html.haml
%ul{ 'ng-controller' => 'ItemsController', 'data-items' => items.to_json }
  %li(ng-repeat="item in items") {{ item.name }}

This is my favorite approach in cases where a JSON endpoint doesn’t make sense. The $element dependency can be mocked, so the code is easily-testable. It doesn’t rely on global variables, so the app is still nicely encapsulated. On top of that, we also avoid making another request.

]]> Sat, 31 Jan 2015 00:00:00 UT https://ndreynolds.com/posts/2015-01-31-getting-angular-and-rails-talking.html Nick Reynolds Testing Rails apps with RSpec: Part II https://ndreynolds.com/posts/2015-01-20-rspec-intro-part2.html In this two-part series, I cover testing a Rails application using RSpec and some other popular gems. If you missed Part 1, you can catch up here.

In Part 2, with the setup out of the way, we’ll dive into writing tests for the various components of a Rails app.

Before diving in, I will say that some of this may be a bit opinionated. When I’m testing a Rails app, my goal is to get the most bang for my buck—that is, the most test coverage for the fewest lines of test code. If you find that a test requiring extensive mocking or brittle networking logic begins taking up more than its share of your development time, in my book it’s fine to just git rm it and move on. Likewise, while getting to 100% coverage is a noble goal, it isn’t always as realistic (in the face of schedule and budget constraints) or as helpful (think: future refactoring) as it might seem. The real objective isn’t to hit some arbitrary percentage—it’s to make your app more reliable for your users and prevent regressions as you develop it.

Overview

In this article, we’ll write tests that touch on each part of the Rails MVC architecture:

  • Model specs test your Rails models—scopes, validations, custom methods
    • Ex: spec/models/post_spec.rb
  • Controller specs test your Rails controllers—CRUD, requests, sessions, param shuffling, formats
    • Ex: spec/controllers/posts_controller_spec.rb
  • Feature (a.k.a. Acceptance) specs test your Rails app from the browser as a user—use cases, interactions, and maybe even some JavaScript
    • Ex: spec/features/post_management_spec.rb

In addition to those, while not covered here, you might also decide to write unit tests for other parts of your app:

  • library code
  • helpers and concerns
  • JavaScript

Model specs

If you’re familiar with unit testing, testing Rails models isn’t much different. Model tests—unlike controller and feature tests—don’t require much environment setup or mocking. This is one of the reasons it’s a good idea to move logic out of the controller and into the model (or maybe a service object)—it’s much easier to test that way.

In a model spec, I’ll generally have expectations for validations and any non-trivial class or instance methods. The goal of each example in a model spec is to verify the behavior of the method or validation. When thinking about what to test, we want to both make sure that it works in the normal case, as well as in certain exceptional cases. Consider some example “what-ifs” when a plain old Ruby method is called:

  • If the method takes an argument, what happens if it’s nil?
  • If the method takes an argument, what happens if the wrong type is passed or the argument is invalid in some other way (e.g., empty, wrong encoding)?
  • If the method has any special behavior based on the arguments or instance state, what happens when that special behavior runs? Does it work correctly?
  • If a number is to be divided by another number, what if the divisor is 0?

While we won’t (and can’t) think of everything that could go wrong, it’s a good idea to touch on common failure points.

In these examples, imagine we’re building an app to compare cars, trucks, and SUVs. To that end, we’ll have a Vehicle model with attributes like the vehicle’s make, model, year and style.

Defining Factories

To make it easier to generate instances of our model in specs, we’ll create factories using the factory_girl gem. Here’s an example factory definition for our Vehicle model that we’ll use in future examples:

In the factory definition above, we describe how to create a vehicle by assigning some default values for each attribute. To use the new factory, we’ll just need to call build(:vehicle) (to make an instance) or create(:vehicle) (to make an instance and persist it to the data store) inside the specs. More on that in a moment.

We also define two traits, one for trucks and one for SUVs. Traits allow you to easily apply a group of attributes to your factory. How you use them is largely up to you. In short, traits let us write this:

…instead of this:

One approach you might also consider is generating random data in your factories. This had the advantage of making sure your app works with a broader range of inputs. The ffaker gem is great for this purpose. In essence, ffaker generates fake data for a number of common fields like names, phone numbers, addresses, and as it happens: vehicles. Here’s how we might re-define the vehicle factory with ffaker:

Notice that we need to use blocks for these calls so that they’re reevaluated each time. To be completely correct here, you could add additional logic to ensure that the make, model, year and style all agree. With this definition, we might generate a 1950 Tesla F-150 car, but for some tests that’s okay. Here’s how you could go improving this:

Testing Validations

Imagine we’d like to require that all vehicles have a year. When users enter new vehicles without a year, validation should fail and they should be required to enter it in order to continue. To make sure that happens, we’ll need to ensure that our validation in the Vehicle model is working correctly.

The model definition:

The model spec:

In case you’re not familiar with RSpec’s DSL, we’ll take a quick detour and cover the three important pieces here:

  • describe defines a group of examples and takes the entity (e.g., model, method, etc.) being specified.
  • it defines an example and takes a description of the example. You’ll want to phrase the description in a way that it reads like English (e.g., it 'raises an exception when...').
  • expect makes an expectation (a.k.a. an assertion in other testing frameworks) about its argument. The expect method takes an object or block and is typically used with to or to_not and a matcher (e.g., be_valid, eq(42), or raise_error).

Going back to the example spec, our first example (“it has a valid factory”) is the control. We want to make sure that a model without a year is invalid, but first we need to make sure that there are any valid inputs at all. Here we verify that the model generated by our factory is valid.

In the second example, we build another model, but this time override the year and set it to nil. With the year is missing, we expect the model to be invalid.

Testing Methods

Imagine our app will display the average fuel-efficiency (MPG) for each vehicle based on user-submitted values. There’s now an MpgSubmission model and a has_many relationship defined in the Vehicle model. To quickly get the average MPG for a vehicle, we’ll add an average_mpg method to the Vehicle model that will average the MPG submissions.

To make it interesting, we’ll add an additional constraint: if there are fewer than 10 submissions, the method should return nil to indicate insufficient data.

I like to create a describe block for each method that will be tested, using the syntax #instance_method and .class_method to indicate what is being described. This helps with quickly associating example groups with the source code being tested.

In the above spec, we test both sides of the if-expression—an example for the case that there are fewer MPG submissions than required and an example for the case that the requirement is met. In the latter case, we also verify that the average agrees with our test data.

While there may be other scenarios we could test here, these examples cover this method fairly well—all branches are tested and there are no obvious nil issues (ActiveRecord::Calculations.average will handle nil mpg values and we’d likely have a database constraint to eliminate that possibility anyway).

Controller specs

If most of the logic is kept out of your controllers, writing controller specs is easy. Controller specs test your Rails application at the request level. Here are some of the questions you should ask when testing controller actions:

  • If the action should render a view, does it do so?
  • If the action should redirect to another action, does it do so?
  • If the action creates, updates, or deletes a resource, does this functionality work?
    • Specifically, how does creating, updating or deleting items affect the number of records after the request is completed?
  • If the session and/or cookie should be updated, is that working correctly?
  • If the request takes or requires certain parameters, what happens if these are missing or invalid?
  • If access to the action is restricted, does the authentication and authorization logic work as expected?
  • Does the action return the correct status code? (important for json format)

There’s a lot going on in the above specs. We use the context

Feature (a.k.a, Acceptance) specs

Feature specs are a type of integration test. Whereas unit tests are concerned with individual components, integration tests focus on how they work together. An app with unit tests but no integration tests is like a pile of individually-tested car parts with no assurance that they can work together to make a drivable car.

In that sense, feature specs are the place to ensure that all the pieces of your Rails app work together and achieve the functionality you built it for. In feature specs, we assume the role of the user and play out various scenarios. For example, some common scenarios in many applications:

  • A user signs up for a new account.
  • A user logs in to the site.
  • A user submits a form (with or without all required fields).
  • An admin manages content.

To write feature specs for Rails, we’ll use Capybara, a Ruby gem which lets us automate the browser to interact with web pages like a user would—that is, by clicking, typing and selecting.

The following is a basic feature spec for logging in to the site. We’ll visit the sign in url, fill in credentials, and submit the form. To verify that we were successful, we’ll then look for a success message afterwards.

With feature specs, it’s important to maintain a certain level of abstraction. If you’ve written good model and controller specs, you don’t need to be concerned with the low-level details here. While we might take a cursory glance at the database to ensure that the expected change was actually made, we’re primarily concerned with the user seeing what they should be seeing. In this case: seeing is believing.

Interacting with JavaScript

It’s likely that at one point or another, your feature specs will need to interact with JavaScript-dependent functionality—maybe there’s a confirmation dialog that needs to be accepted or content that is loaded dynamically.

Although Capybara’s default Rack::Test driver does not support JavaScript, it’s easy enough to switch to one that does for feature specs requiring it. You can read more about the available drivers here. If you plan to run specs on a server without X11 (or an alternative) installed, PhantomJS via Poltergeist is a good choice.

The below example, while contrived, demonstrates how expectations can be made about dynamic content, as well as how JavaScript code can be executed from the feature spec.

As an aside, trying to test JS-heavy apps from Capybara can unfortunately be a world of pain. As the setup typically involves multiple threads or processes—your Rails app being one and the browser being the other—it leads to all sorts of timing issues. Race conditions, driver differences, and random AJAX failures all conspire to make these tests brittle and hard to debug. I’ve started to avoid these types of tests altogether and rely instead on client-side testing with Mocha and Karma for JS-heavy pages.

Wrapping Up

One thing you may have noticed is that controller specs have a good deal of overlap with model and feature specs. While there are advantages to having controller specs, I’ve found that most things they test can be covered by feature specs. If you only have time for one or the other, go with feature specs. They prove that your app works in an actual browser—rather than just from a cURL client, which is as far as controller specs will get you.

More Resources

]]> Tue, 20 Jan 2015 00:00:00 UT https://ndreynolds.com/posts/2015-01-20-rspec-intro-part2.html Nick Reynolds Testing Rails apps with RSpec: Part I https://ndreynolds.com/posts/2014-07-15-rspec-intro-part1.html In this two-part series, I’ll cover testing a Rails application—from how to get set up with the latest toolchain, to writing those first tests.

In Part 1, I’ll look at how to set up and configure RSpec 3 (with Factory Girl and Capybara) for a Rails 4 app, and how to generate and run your first specs. Next time, in Part 2, we’ll look at writing model, controller and feature specs.

But first, why write tests?

I was initially very wary of unit-testing. While I knew that I needed to make sure the app worked, I was skeptical of the time tradeoff. The first few tests can seem like more trouble than they’re worth, and quite honestly, those first few probably are more trouble than they’re worth. But after a while, writing tests becomes second nature. I think it can easily take less time to write automated tests than to manually test every feature before every release.

It’s no silver bullet. There will probably still be bugs from scenarios you never thought to test. But even if they can’t catch every bug, tests provide you with confidence that your app works as intended on a basic level. This is all the more important if you didn’t write the app to begin with, or if you’re part of a big team—you won’t always know what effects your changes might have. There might be features you don’t even know about. Ultimately, a solid test suite means less to worry about for you, the developer, and with any luck, a more stable product for the user.

Testing a Rails 4 app with RSpec 3

I really like RSpec. If you’re more of a minimalist, you can always skip the extra gems and use the built-in minitest, but I like the additional features and clean DSL that RSpec provides. For example, to test that a variable is nil:

It’s a matter of taste, but I prefer RSpec’s more human-readable style. Here, we’ll use RSpec 3.0, which landed back in May, and brings a few new changes into the fold (See here for more info: Notable Changes in RSpec 3).

In addition to RSpec, we’ll also set up Factory Girl as a fixture replacement, Capybara for browser-level acceptance (a.k.a. integration) tests, and Database Cleaner for cleaning up between test scenarios.

When you write tests, you’ll need test data. As a fixture replacement, Factory Girl helps you build instances of your models for use in test scenarios. This is accomplished through factories in which you define how to build the instances. Although it’s nothing you couldn’t do yourself with plain old ActiveRecord methods and some helper methods, Factory Girl provides a nice system for setting defaults (and then overriding them) that keeps a lot of boilerplate out of your code.

Acceptance tests look at how the system as a whole functions. For a Rails app, that usually means typing and clicking on things in a web browser and seeing some sort of response. Capybara provides one DSL for automating various browsers to simulate user interactions with your app, which you can then make expectations about using RSpec. Because it provides a single interface to various browsers, it gives you the freedom to do things like use Selenium to run certain tests while using headless webkit to run others.

By default, test scenarios are wrapped in a database transaction so that each scenario’s changes can be rolled back, so as to not cause side effects when running other scenarios later. But when using Capybara’s JavaScript driver, this causes some trouble, as these scenarios are run in another thread which doesn’t share the database connection, leading to unexpected behavior. To avoid headaches down the road, we’ll also use the database_cleaner gem to adjust the way the database cleanup is done. (See this post for more details.)

Configure your Gemfile

Let’s get started. Assuming you’re working inside a new Rails 4 app, add the following to your Gemfile and then bundle install.

Run generators

Next, run the RSpec generator to create the initial skeleton:

rails generate rspec:install

Configure Capybara

To make Capybara available from within RSpec specs, add the following line to spec/rails_helper.rb:

Your Capybara feature specs will also need a home, add the spec/features/ directory:

mkdir spec/features

Configure database_cleaner

Next, make the following adjustments to spec/rails_helper.rb to integrate the database_cleaner gem:

The .rspec file

By default, RSpec generates a .rspec file in your app’s root. This allows you to set different command line options (see rspec -h) that will be automatically picked up. The default .rspec includes the --warnings option, which can be really noisy even in a brand new Rails app. If you see a lot of warnings later on, you can hide them by removing this line.

Generating specs

The next time you run rails generate resource, Rails should already be configured to generate specs under spec/ and factories under spec/factories.

Let’s try that out with the proverbial Rails blog example:

rails generate resource post title:string content:text published:boolean

If everything’s correctly configured, you should see something close to this:

invoke  active_record
create    db/migrate/20140630160246_create_posts.rb
create    app/models/post.rb
invoke    rspec
create      spec/models/post_spec.rb
invoke      factory_girl
create        spec/factories/posts.rb
invoke  controller
create    app/controllers/posts_controller.rb
invoke    erb
create      app/views/posts
invoke    rspec
create      spec/controllers/posts_controller_spec.rb
invoke    helper
create      app/helpers/posts_helper.rb
invoke      rspec
create        spec/helpers/posts_helper_spec.rb
invoke    assets
invoke      coffee
create        app/assets/javascripts/posts.js.coffee
invoke      scss
create        app/assets/stylesheets/posts.css.scss
invoke  resource_route
 route    resources :posts

Note the factory at spec/factories/posts.rb, the model spec at specs/models/post_spec.rb, and the controller spec at specs/controllers/post_controller_spec.rb.

With the new specs in place, try running rspec (you can also run rake), to see the results. So far, you should only see a few pending specs:

**

Pending:
  PostsHelper add some examples to (or delete) ./spec/helpers/posts_helper_spec.rb
    # Not yet implemented
    # ./spec/helpers/posts_helper_spec.rb:14
  Post add some examples to (or delete) ./spec/models/post_spec.rb
    # Not yet implemented
    # ./spec/models/post_spec.rb:4

Wrapping Up

Now that everything is set up, we’re ready to write some tests. Stay tuned for Part 2. In the meantime, here are a few more resources worth a read:

]]> Tue, 15 Jul 2014 00:00:00 UT https://ndreynolds.com/posts/2014-07-15-rspec-intro-part1.html Nick Reynolds