Testing directions with ASCII art

Classifying maneuvers is one of the most important things that our Directions API does for developers building apps with turn-by-turn navigation. When you’re driving, it’s what determines the difference between a turn right, turn slightly right, and keep right, for example. Classifying maneuvers is complex because there are virtually endless possibilities for each intersection we must handle - the world is full of very odd intersections. When we encounter a problematic intersection, we capture its characteristics in an automated test to make sure the way we handle the intersection doesn’t break in the future.

But, here’s the next challenge - how do we quickly create test data for all of these special cases? OSRM (the software that powers our Directions API behind the scenes) reads data in OpenStreetMap format, so we use a tool that translates ASCII art of an intersection to a valid OpenStreetMap extract, then push the data for that scenario through the entire engine to make sure it behaves correctly.

In our ASCII test definitions, letters a-z identify OSM nodes to be generated and all other characters provide a visual aide to help developers understand the scenario being tested.

Our scenarios range from simple intersections:

      l   m
      |   |
      |   |
  _ _ g---h_
f'    |   |  '_
      |   |     i
      |   |
   _ _b---c__
a'    |   |    'd
      |   |
      j   k

to more complex ones:

          e
a - b - - c - d'f|l'
          m
          g
          |
         .h-_
    k - i    |'.j.'

and even extremely complex situations like this bridge in Berlin:

      q          s
      p          o
      ..        ..
     .    .   .    .
j - i - - - h - - - g - f> k <   > l <
a - b - - - c - - - d - e
     .    .  .     .
      ..        ..
      m          n
      t          r

This must be what it’s like playing hopscotch in The Simpsons.

The tools in their current form were made possible by OSRM contributor @emiltin, creator of I Bike CPH.

Our guidance test suite already covers 458 scenarios and spans 13,139 lines of ASCII definitions. This growing set of scenarios ensures that our turn-by-turn instructions improve as we discover more special cases.

Sometimes you can nearly feel the waves:

j----a---c---b----k
       ~   ~  ~
          ~  ~ ~
              ~~~
                d
                  ~
                    ~
                      ~
                        e --- f