home

2019-03-23-gotest-tools-poll.org (5193B)

---

 #+TITLE: Golang testing — gotest.tools poll
 #+date: <2019-03-23 Sat>
 #+filetags: go testing poll
 
 #+TOC: headlines 2
 
 * Introduction
 Let's continue the [[https://gotest.tools][=gotest.tools=]] serie, this time with the =poll= package.
 
 #+BEGIN_QUOTE
 Package poll provides tools for testing asynchronous code.
 #+END_QUOTE
 
 When you write test, you may test a piece of code that work asynchronously, where the
 state you're expecting is gonna take a bit of time to be achieved. This is especially true
 when you work on networking or file-system code. And this happens a lot when you write
 integration (or end-to-end) test, less for unit-tests.
 
 The package =poll= is trying to tackle those use cases. We'll first take a look at the
 main function, =WaitOn=, then how to write a ~Check~, using the ~Result~ type.
 
 * ~WaitOn~
 
 Let's look into the main ~poll~ function : `WaitOn`.
 
 #+begin_quote
  WaitOn a condition or until a timeout. Poll by calling check and exit when check returns
  a done Result. To fail a test and exit polling with an error return a error result.
 #+end_quote
 
 In a gist, ~WaitOn~ will run a /condition/ function until it either times out or
 succeed. It wait for a given time/delay between each run.
 
 #+begin_src go
   func WaitOn(t TestingT, check Check, pollOps ...SettingOp) {
           // […]
   }
 #+end_src
 
 As any /testing helper/ function, the first argument is ~*testing.T~ (or, in this case,
 any thing that look like it, thanks to the ~TestingT~ interace). The two other arguments
 are way more interesting :
 
 - The ~Check~ is the condition that will run multiple times until it either timeout, or succeed.
 - The ~SettingOp(s)~ which are options to configure the function, things like the timeout,
   or the /delay/ between each run.
 
 The settings are pretty straightforward :
 
 - ~WithDelay~ : sets the delay to wait between polls. The default delay is 100ms.
 - ~WithTimeout~ : sets the timeout. The default timeout is 10s.
 
 There is existing ~Check~ for common case:
 
 - ~Connection~ : try to open a connection to the address on the named network.
 
   #+begin_src go
     poll.WaitOn(t, poll.Connection("tcp", "foo.bar:55555"), poll.WithTimeout("5s"))
   #+end_src
 
 - ~FileExists~ : looks on filesystem and check that path exists.
 
   #+begin_src go
     poll.WaitOn(t, poll.FileExists("/should/be/created"), poll.WithDelay("1s"))
   #+end_src
 
 
 * ~Check~ and ~Result~
 
 ~Connection~ and ~FileExists~ are the only two /built-in/ ~Check~ provided by
 ~gotest.tools~. They are useful, but as usual, where ~gotest.tools~ shines is
 extensiblity. It is really easy to define your own ~Check~.
 
 #+begin_src go
   type Check func(t LogT) Result
 #+end_src
 
 A ~Check~ is, thus, only a function that takes ~LogT~ — which is anything that can log
 something, like ~*testing.T~ — and return a ~Result~. Let's look at this intersting
 ~Result~ type.
 
 #+begin_src go
   type Result interface {
       // Error indicates that the check failed and polling should stop, and the
       // the has failed
       Error() error
       // Done indicates that polling should stop, and the test should proceed
       Done() bool
       // Message provides the most recent state when polling has not completed
       Message() string
   }
 #+end_src
 
 Although it's an interface, the ~poll~ package defines built-in ~Result~ so that it's easy
 to write ~Check~ without having to define you ~Result~ type.
 
 - ~Continue~ returns a Result that indicates to WaitOn that it should continue
   polling. The message text will be used as the failure message if the timeout is reached.
 - ~Success~ returns a Result where Done() returns true, which indicates to WaitOn that it
   should stop polling and exit without an error.
 - ~Error~ returns a Result that indicates to WaitOn that it should fail the test and stop
   polling.
 
 The basic just to write a ~Check~ is then :
 
 - if the state is not there yet, return ~Continue~,
 - if there is an error, unrelated to validating the state, return an ~Error~,
 - if the state is there, return ~Success~.
 
 Let's look at an example taken from the ~moby/moby~ source code.
 
 #+begin_src go
   poll.WaitOn(t, container.IsInState(ctx, client, cID, "running"), poll.WithDelay(100*time.Millisecond))
 
   func IsInState(ctx context.Context, client client.APIClient, containerID string, state ...string) func(log poll.LogT) poll.Result {
           return func(log poll.LogT) poll.Result {
                   inspect, err := client.ContainerInspect(ctx, containerID)
                   if err != nil {
                           return poll.Error(err)
                   }
                   for _, v := range state {
                           if inspect.State.Status == v {
                                   return poll.Success()
                           }
                   }
                   return poll.Continue("waiting for container to be one of (%s), currently %s", strings.Join(state, ", "), inspect.State.Status)
           }
   }
 #+end_src
 
 
 * Conclusion
 
 … that's a wrap. The =poll= package allows to easily wait for a condition to happen in a
 given time-frame — with sane defaults. As for most of the ~gotest.tools~ package, we use
 this package heavily in =docker/*= projects too…