nbtests

Documentation

Overview

Package nbtests holds tools to run functional tests for GoNB using `nbconvert`.

The actual tests are instrumented in `nbtests_test.go`, but this package exports several tools that would allow one to instrument tests for their own notebooks elsewhere, if for some reason it is handy.

Index

• Constants
• func Check(r io.Reader, expectation ExpectFn, print bool) error
• func GoNBRootDir() string
• func InputLine(cell int) string
• func InstallTmpGonbKernel(runArgs, extraInstallArgs []string) (tmpJupyterDir string, err error)
• func OutputLine(cell int) string
• type ExpectFn
  • func Capture(capturedLine *string) ExpectFn
  • func Match(search ...string) ExpectFn
  • func Sequence(expectations ...ExpectFn) ExpectFn

Constants

const Separator = "----" // String used as separator by `nbconvert` in text mode.

Functions

func Check

func Check(r io.Reader, expectation ExpectFn, print bool) error

Check that the input given in reader matches the `want` expectation. Returns nil is expectation was matched, or an error with the failed match description.

If `print` is set, it also prints the lines read from `r`.

func GoNBRootDir

func GoNBRootDir() string

func InputLine

func InputLine(cell int) string

InputLine returns the line that precedes the cell input as written by `nbconvert -to asciidoc`. This is a convenience to add to the testing of notebooks.

func InstallTmpGonbKernel

func InstallTmpGonbKernel(runArgs, extraInstallArgs []string) (tmpJupyterDir string, err error)

InstallTmpGonbKernel will create a temporary directory, set the environment variable JUPYTER_DATA_DIR to that directory, and compile and install GoNB to that directory, so it will be used by `nbconvert`.

It also compiles `nbexec` to the same directory, which is used to controle the execution of the notebooks.

Parameters:

• `gonbRunArgs` are passed to `go run --cover <gonbRunArgs> .` command, executed from GoNB's root directory.
• `extraInstallArgs` are passed to the `gonb --install` execution. Typical values here include `--logtostderr`, and `--vmodule=...` for verbose output.

Notice that this precludes concurrent testing of various versions of GoNB in the same process, since it relies on this one global environment variable (JUPYTER_DATA_DIR) -- but one can still run different processes concurrently.

func OutputLine

func OutputLine(cell int) string

OutputLine returns the line that precedes the output of a cell generated by `nbconvert -to asciidoc`. This is a convenience to add to the testing of notebooks.

Types

type ExpectFn

type ExpectFn func(line string, eof bool) (done bool, err error)

ExpectFn is a function that checks for expectations of an input line. It should return true, if the expectation was matched, false if not yet, or return an error if there was something wrong with the line and it the testing should fail immediately.

When the input is finished, ExpectFn is called with `eof=true`, in which case it should either return true or an error.

See the following functions that return `ExpectFn` that can be used:

Match() Sequence()

func Capture

func Capture(capturedLine *string) ExpectFn

Capture accepts the next line and stores its value in the `capturedLine` variable. This can be used for later processing.

func Match

func Match(search ...string) ExpectFn

Match returns an ExpectFn that checks if the input has the given string. If more than one string is given, they are expected to match consecutively, exactly one line after another.

func Sequence

func Sequence(expectations ...ExpectFn) ExpectFn

Sequence returns an ExpectFn that checks whether each of the given expectations are matched in order. They don't need to be consecutive, that is, there can be unrelated lines in-between.