TestContext

A TestContext simulates the execution of an Elm program.

Creating

type TestContext msg model effect

A TestContext represents an Elm program, a current state for that program, and a log of any errors that have occurred while simulating interaction with the program.

To create a TestContext, see thecreate*` functions below.
To advance the state of a TestContext, see Simulating user input, and Directly sending Msgs
To assert on the resulting state of a TestContext, see Final assertions

create :

{ init : ( model, effect )

, update : msg -> model -> ( model, effect )

, view : model -> Html msg

}

-> TestContext msg model effect

Creates a TestContext from the parts of a standard Html.program.

See other create* functions below if the program you want to test uses flags or nagivation.

createWithFlags :

{ init : flags -> ( model, effect )

, update : msg -> model -> ( model, effect )

, view : model -> Html msg

}

-> flags

-> TestContext msg model effect

Creates a TestContext from the parts of a standard with flags (Html.programWithFlags).

If your program uses Json.Encode.Value as its flags type, you may find createWithJsonStringFlags useful.

If your program does not use flags, see create.

See other create* functions below if the program you want to test uses nagivation.

createWithJsonStringFlags :

Decoder flags

-> { init : flags -> ( model, effect )

, update : msg -> model -> ( model, effect )

, view : model -> Html msg

}

-> String

-> TestContext msg model effect

A simplified way to create a TestContext for a program that decodes its flags with a JSON decoder.

If your program does not use Json.Encode.Value as its flags type, or you want more control over how the flags are provided in your tests, see createWithFlags.

If your program does not use flags, see create.

See other create* functions below if the program you want to test uses nagivation.

createWithBaseUrl :

{ init : ( model, effect )

, update : msg -> model -> ( model, effect )

, view : model -> Html msg

}

-> String

-> TestContext msg model effect

Creates a TestContext from the parts of a standard Html.program and a base URL against which relative URLs can be resolved.

If you don't need to simulate clicking links with relative URLs, prefer create.

If your program uses navigation, see createWithNavigation.

createWithNavigation :

(Location -> msg)

-> { init : Location -> ( model, effect )

, update : msg -> model -> ( model, effect )

, view : model -> Html msg

}

-> String

-> TestContext msg model effect

Creates a TestContext from the parts of a Navigation.program.

See other create* functions above and below if the program you want to test uses flags or does not use nagivation.

createWithNavigationAndFlags :

(Location -> msg)

-> { init : flags -> Location -> ( model, effect )

, update : msg -> model -> ( model, effect )

, view : model -> Html msg

}

-> String

-> flags

-> TestContext msg model effect

Creates a TestContext from the parts of a program with navigation and flags (Navigation.programWithFlags).

If your program uses Json.Encode.Value as its flags type, you may find createWithNavigationAndJsonStringFlags useful.

If your program does not use flags, see createWithNavigation.

If your program does not use navigation, see createWithFlags.

createWithNavigationAndJsonStringFlags :

Decoder flags

-> (Location -> msg)

-> { init : flags -> Location -> ( model, effect )

, update : msg -> model -> ( model, effect )

, view : model -> Html msg

}

-> String

-> TestContext msg model effect

A simplified way to create a TestContext for a program with navigation that decodes its flags with a JSON decoder.

If your program does not use Json.Encode.Value as its flags type, or you want more control over how the flags are provided in your tests, see createWithNavigationAndFlags.

If your program does not use flags, see createWithNavigation.

If your program does not use navigation, see createWithJsonStringFlags.

Simulating user input

clickButton :

String

-> TestContext msg model effect

Simulates clicking a button.

Currently, this function will find and click a <button> HTML node containing the given buttonText.

NOTE: In the future, this function will be generalized to find buttons with accessibility attributes matching the given buttonText.

clickLink :

String

-> String

-> TestContext msg model effect

Simulates clicking a <a href="..."> link.

NOTE: Currently, this function requires that you also provide the expected href. After eeue56/elm-html-test#52 is resolved, a future release of this package will remove the href parameter.

Note for testing single-page apps, if the target <a> tag has an onClick handler, then the message produced by the handler will be processed and the href will not be followed. NOTE: Currently this function cannot verify that the onClick handler sets preventDefault, but this will be done in the future after https://github.com/eeue56/elm-html-test/issues/63 is resolved.

fillIn :

String

-> String

-> TestContext msg model effect

Simulates replacing the text in an input field labeled with the given label.

NOTE: Currently, this function requires that you also provide the field id (which must match both the id attribute of the target input element, and the for attribute of the label element). After eeue56/elm-html-test#52 is resolved, a future release of this package will remove the fieldId parameter.

NOTE: TODO: In the future, this will be generalized to work with labeled textareas as well as labeled input fields. (related to eeue56/elm-html-test#49)

NOTE: In the future, this will be generalized to work with aria accessiblity attributes in addition to working with standard HTML label elements.

If you need to target a <textarea> that does not have a label, see fillInTextarea.

If you need more control over the finding the target element or creating the simulated event, see simulate.

fillInTextarea :

String

-> TestContext msg model effect

Simulates replacing the text in a <textarea>.

This function expects that there is only one <textarea> in the view. If your view has more than one <textarea>, prefer adding associated <label> elements and use fillIn. If you cannot add <label> elements see within.

If you need more control over the finding the target element or creating the simulated event, see simulate.

check :

String

-> String

-> Bool

-> TestContext msg model effect

Simulates setting the value of a checkbox labeled with the given label.

NOTE: In the future, this will be generalized to work with aria accessiblity attributes in addition to working with standard HTML label elements.

If you need more control over the finding the target element or creating the simulated event, see simulate.

routeChange :

String

-> TestContext msg model effect

url may be an absolute URL or relative URL

Simulating user input (advanced)

simulate :

(Single msg -> Single msg)

-> ( String, Value )

-> TestContext msg model effect

Simulates a custom DOM event.

NOTE: If there is another, more specific function (see Simulating user input that does what you want, prefer that instead, as you will get the benefit of better error messages.

Parameters:

findTarget: A function to find the HTML element that responds to the event (typically this will be a call to Test.Html.Query.find [ ...some selector... ])
( eventName, eventValue ): The event to simulate (see Test.Html.Event "Event Builders")

within :

(Single msg -> Single msg)

-> (TestContext msg model effect -> TestContext msg model effect)

-> TestContext msg model effect

Focus on a part of the view for a particular operation.

For example, if your view produces the following HTML:

<div>
  <div id="sidebar">
    <button>Submit</button>
  </div>
  <div id="content">
    <button>Submit</button>
  </div>
</div>

then the following will allow you to simulate clicking the "Submit" button in the sidebar (simply using clickButton "Submit" would fail because there are two buttons matching that text):

import Test.Html.Query as Query
import Test.Html.Selector exposing (id)


testContext
    |> TestContext.within
        (Query.find [ id "sidebar" ])
        (TestContext.clickButton "Submit")
    |> ...

Directly sending Msgs

update : msg -> TestContext msg model effect -> TestContext msg model effect

Advances the state of the TestContext's program by using the TestContext's program's update function with the given msg.

This can be used to simulate events that can only be triggered by commands (Cmd) and subscriptions (Sub) (i.e., that cannot be triggered by user interaction with the view).

NOTE: When possible, you should prefer Simulating user input, as doing so will make your tests more robust to changes in your program's implementation details.

Final assertions

expectViewHas : List Selector -> TestContext msg model effect -> Expectation

A simpler way to assert that a TestContext's view matches a given selector.

expectViewHas [...selector...] is the same as expectView (Test.Html.Query.has [...selector...]).

expectView :

(Single msg -> Expectation)

-> TestContext msg model effect

-> Expectation

Makes an assertion about the current state of a TestContext's view.

expectLastEffect :

(effect -> Expectation)

-> TestContext msg model effect

-> Expectation

Makes an assertion about the last effect produced by a TestContext's program.

expectModel : (model -> Expectation) -> TestContext msg model effect -> Expectation

Make an assertion about the current state of a TestContext's model.

expectPageChange : String -> TestContext msg model effect -> Expectation

Asserts that the program ended by navigating away to another URL.

Intermediate assertions

These functions can be used to make assertions on a TestContext without ending the test.

shouldHave :

List Selector

-> TestContext msg model effect

shouldHave [...selector...] is equivalent to shouldHaveView (Test.Html.Query.has [...selector...])

shouldNotHave :

List Selector

-> TestContext msg model effect

shouldNotHave [...selector...] is equivalent to shouldHaveView (Test.Html.Query.hasNot [...selector...])

shouldHaveView :

(Single msg -> Expectation)

-> TestContext msg model effect

Validates the the current state of a TestContext's view without ending the TestContext.

shouldHaveLastEffect :

(effect -> Expectation)

-> TestContext msg model effect

Validates the last effect produced by a TestContext's program without ending the TestContext.

To end a TestContext without using a final assertion, use the following function:

done : TestContext msg model effect -> Expectation

Ends a TestContext, reporting any errors that occurred.

NOTE: You should prefer using a final assertion to end your test over using done, as doing so will make the intent of your test more clear.

Custom assertions

These functions may be useful if you are writing your own custom assertion functions.

fail :

String

-> String

-> TestContext msg model effect

fail can be used to report custom errors if you are writing your own convenience functions to deal with test contexts.

Example (this is a function that checks for a particular structure in the program's view, but will also fail the TestContext if the expectedCount parameter is invalid):

expectNotificationCount : Int -> TestContext Msg Model effect -> TestContext Msg Model effect
expectNotificationCount expectedCount testContext =
    if expectedCount <= 0 then
        testContext
            |> TestContext.fail "expectNotificationCount"
                ("expectedCount must be positive, but was: " ++ toString expectedCount)
    else
        testContext
            |> shouldHave
                [ Test.Html.Selector.class "notifications"
                , Test.Html.Selector.text (toString expectedCount)
                ]

Modules

TestContext

avh4/elm-program-test/1.1.0

TestContext

Creating

Simulating user input

Simulating user input (advanced)

Directly sending Msgs

Final assertions

Intermediate assertions

Custom assertions

Modules