A test which has yet to be evaluated. When evaluated, it produces one or more Expectations.

See test and fuzz for some ways to create a Test.

Return a Test that evaluates a single Expectation.

import Test exposing (fuzz)
import Expect




test "the empty list has 0 length" <|
    \_ ->
        List.length []
            |> Expect.equal 0

Apply a description to a list of tests.

import Test exposing (describe, test, fuzz)
import Fuzz exposing (int)
import Expect




describe "List"
    [ describe "reverse"
        [ test "has no effect on an empty list" <|
            \_ ->
                List.reverse []
                    |> Expect.equal []
        , fuzz int "has no effect on a one-item list" <|
            \num ->
                 List.reverse [ num ]
                    |> Expect.equal [ num ]
        ]
    ]

Passing an empty list will result in a failing test, because you either made a mistake or are creating a placeholder.

Run each of the given tests.

concat [ testDecoder, testSorting ]

Returns a Test that is "TODO" (not yet implemented). These tests always fail, but test runners will only include them in their output if there are no other failures.

These tests aren't meant to be committed to version control. Instead, use them when you're brainstorming lots of tests you'd like to write, but you can't implement them all at once. When you replace todo with a real test, you'll be able to see if it fails without clutter from tests still not implemented. But, unlike leaving yourself comments, you'll be prompted to implement these tests because your suite will fail.

describe "a new thing"
    [ todo "does what is expected in the common case"
    , todo "correctly handles an edge case I just thought of"
    ]

This functionality is similar to "pending" tests in other frameworks, except that a TODO test is considered failing but a pending test often is not.

Returns a Test that gets skipped.

Calls to skip aren't meant to be committed to version control. Instead, use it when you want to focus on getting a particular subset of your tests to pass. If you use skip, your entire test suite will fail, even if each of the individual tests pass. This is to help avoid accidentally committing a skip to version control.

See also only. Note that skip takes precedence over only; if you use a skip inside an only, it will still get skipped, and if you use an only inside a skip, it will also get skipped.

describe "List"
    [ skip <| describe "reverse"
        [ test "has no effect on an empty list" <|
            \_ ->
                List.reverse []
                    |> Expect.equal []
        , fuzz int "has no effect on a one-item list" <|
            \num ->
                 List.reverse [ num ]
                    |> Expect.equal [ num ]
        ]
    , test "This is the only test that will get run; the other was skipped!" <|
        \_ ->
            List.length []
                |> Expect.equal 0
    ]

Returns a Test that causes other tests to be skipped, and only runs the given one.

Calls to only aren't meant to be committed to version control. Instead, use them when you want to focus on getting a particular subset of your tests to pass. If you use only, your entire test suite will fail, even if each of the individual tests pass. This is to help avoid accidentally committing a only to version control.

If you you use only on multiple tests, only those tests will run. If you put a only inside another only, only the outermost only will affect which tests gets run.

See also skip. Note that skip takes precedence over only; if you use a skip inside an only, it will still get skipped, and if you use an only inside a skip, it will also get skipped.

describe "List"
    [ only <| describe "reverse"
        [ test "has no effect on an empty list" <|
            \_ ->
                List.reverse []
                    |> Expect.equal []
        , fuzz int "has no effect on a one-item list" <|
            \num ->
                 List.reverse [ num ]
                    |> Expect.equal [ num ]
        ]
    , test "This will not get run, because of the `only` above!" <|
        \_ ->
            List.length []
                |> Expect.equal 0
    ]

Take a function that produces a test, and calls it several (usually 100) times, using a randomly-generated input from a Fuzzer each time. This allows you to test that a property that should always be true is indeed true under a wide variety of conditions. The function also takes a string describing the test.

These are called "fuzz tests" because of the randomness. You may find them elsewhere called property-based tests, generative tests, or QuickCheck-style tests.

import Test exposing (fuzz)
import Fuzz exposing (list, int)
import Expect




fuzz (list int) "List.length should always be positive" <|
    -- This anonymous function will be run 100 times, each time with a
    -- randomly-generated fuzzList value.
    \fuzzList ->
        fuzzList
            |> List.length
            |> Expect.atLeast 0

Run a fuzz test using two random inputs.

This is a convenience function that lets you skip calling Fuzz.tuple.

See fuzzWith for an example of writing this in tuple style.

import Test exposing (fuzz2)
import Fuzz exposing (list, int)




fuzz2 (list int) int "List.reverse never influences List.member" <|
    \nums target ->
        List.member target (List.reverse nums)
            |> Expect.equal (List.member target nums)

Run a fuzz test using three random inputs.

This is a convenience function that lets you skip calling Fuzz.tuple3.

Run a fuzz test using four random inputs.

This is a convenience function that lets you skip calling Fuzz.tuple4.

Run a fuzz test using five random inputs.

This is a convenience function that lets you skip calling Fuzz.tuple5.

Run a fuzz test with the given FuzzOptions.

Note that there is no fuzzWith2, but you can always pass more fuzz values in using Fuzz.tuple, Fuzz.tuple3, for example like this:

import Test exposing (fuzzWith)
import Fuzz exposing (tuple, list, int)
import Expect




fuzzWith { runs = 4200 }
    (tuple ( list int, int ))
    "List.reverse never influences List.member" <|
        \(nums, target) ->
            List.member target (List.reverse nums)
                |> Expect.equal (List.member target nums)

Options fuzzWith accepts. Currently there is only one but this API is designed so that it can accept more in the future.

runs

The number of times to run each fuzz test. (Default is 100.)

import Test exposing (fuzzWith)
import Fuzz exposing (list, int)
import Expect




fuzzWith { runs = 350 } (list int) "List.length should always be positive" <|
    -- This anonymous function will be run 350 times, each time with a
    -- randomly-generated fuzzList value. (It will always be a list of ints
    -- because of (list int) above.)
    \fuzzList ->
        fuzzList
            |> List.length
            |> Expect.atLeast 0