Expect

Expectations for tests.

An expectation that does not hold aborts through the Expect effect, so a test body is a plain sequence of statements and the first failing expectation ends it. Test.run handles the effect around each test and reports the failure; a body can also handle it itself, as onFail does. The expected value comes first, so actual |> Expect.equal expected and List.length xs |> Expect.lessThan 10 read as written.

Because a failure aborts, ok, err, and just return the value they unwrap: n = Expect.ok (parse "12") followed by Expect.equal 12 n. Asserting that code fails means handling the code’s own effect inside the body, with Fail.attempt say, and asserting on the Result.

Failure messages render operands with Inspect, which shows values that have a Show instance and writes <value> for the rest, so a type can be tested without deriving Show.

Error

type Error =    { message : String    , location : Maybe Frame    }Source

Why an expectation failed.

Fields

message

message : StringSource

The failure text. It may span several lines, separated by \n and without a trailing newline; a report indents each.

location

location : Maybe FrameSource

Where the expectation was made: the innermost frame of the call stack outside this module, so a test body sees its own line and a helper defined elsewhere sees the line inside the helper.

Instances:

Eq Error
Show Error

Inspect

class Inspect aSource

Text for a value in a failure message.

The two blanket instances make every type inspectable: a type with a Show instance is shown, and any other reads <value>. A type may declare its own instance to override either.

import Expect exposing (inspect)
import Process

inspect (Just "a") == "Just \"a\""
inspect Process.success == "<value>"

Methods

inspect

inspect : Inspect a => a -> StringSource

The value’s text in a failure message.

Instances:

Inspect a
Show a => Inspect a

Expect

effect ExpectSource

A failed expectation. A body that performs it is a test, and Test.run or a handler of the caller’s own decides what a failure means.

Operations

fail

abort fail : Error ->{Expect} aSource

Fails with the error. It never returns: it unwinds to the nearest enclosing handler.

atLeast

atLeast : (Ord a, Inspect a) => a -> a ->{Expect} ()Source

Fails unless actual is greater than or equal to bound.

atMost

atMost : (Ord a, Inspect a) => a -> a ->{Expect} ()Source

Fails unless actual is less than or equal to bound.

equal

equal : (Eq a, Inspect a) => a -> a ->{Expect} ()Source

Fails unless actual equals expected.

import Expect exposing (Expect)
import Maybe exposing (Maybe(..))

message : (() ->{Expect} ()) -> Maybe String
message body =
    handle body() on
        Expect.fail error -> Just error.message
        return _ -> Nothing

message { Expect.equal 1 1 } == Nothing
message { Expect.equal [1, 2] [1] } == Just "Expected: [1, 2]\nActual:   [1]"

err

err : Inspect b => Result a b ->{Expect} aSource

The error of an Err, failing on an Ok.

failWith

failWith : String ->{Expect} aSource

Fails with the message as it is.

greaterThan

greaterThan : (Ord a, Inspect a) => a -> a ->{Expect} ()Source

Fails unless actual is greater than bound.

just

just : Maybe a ->{Expect} aSource

The value of a Just, failing on Nothing.

import Expect exposing (Expect)
import Maybe exposing (Maybe(..))

passes : (() ->{Expect} ()) -> Bool
passes body =
    handle body() on
        Expect.fail _ -> False
        return _ -> True

passes { Expect.equal 3 (Expect.just (Just 3)) }
passes { Expect.nothing (Just 3) } == False

lessThan

lessThan : (Ord a, Inspect a) => a -> a ->{Expect} ()Source

Fails unless actual is less than bound: x |> Expect.lessThan 10.

notEqual

notEqual : (Eq a, Inspect a) => a -> a ->{Expect} ()Source

Fails when actual equals unexpected.

nothing

nothing : Inspect a => Maybe a ->{Expect} ()Source

Fails unless the value is Nothing.

ok

ok : Inspect a => Result a b ->{Expect} bSource

The value of an Ok, failing on an Err.

import Expect exposing (Expect)
import Result exposing (Result(..))

parsed : Result String Int
parsed = Ok 12

rejected : Result String Int
rejected = Err "bad"

passes : (() ->{Expect} ()) -> Bool
passes body =
    handle body() on
        Expect.fail _ -> False
        return _ -> True

passes { Expect.equal 12 (Expect.ok parsed) }
passes { Expect.equal "bad" (Expect.err rejected) }
passes { Expect.equal 0 (Expect.ok rejected) } == False

onFail

onFail : String -> (() ->{Expect, e} a) ->{Expect, e} aSource

Runs the body, adding a line of context above the message of any failure it raises. As a block item, use Expect.onFail "after parsing" applies to the rest of the block.

import Expect exposing (Expect)
import Maybe exposing (Maybe(..))

message : (() ->{Expect} ()) -> Maybe String
message body =
    handle body() on
        Expect.fail error -> Just error.message
        return _ -> Nothing

message { Expect.onFail "the count" { Expect.equal 1 2 } } == Just "the count\nExpected: 1\nActual:   2"
message { Expect.onFail "the count" { Expect.equal 1 1 } } == Nothing