brian-watkins / elm-spec / Spec.Markup

Target, observe and make claims about HTML elements.

Target an HTML Element

target : ( Selector a, Spec.Step.Context model ) -> Spec.Step.Command msg

A step that identifies an element to which later steps will be applied.

Spec.when "the button is clicked twice"
  [ Spec.Markup.target << by [ tag "button" ]
  , Spec.Markup.Event.click
  , Spec.Markup.Event.click
  ]

Observe HTML Elements


type MarkupObservation a

Represents an observation of HTML.

observeElements : MarkupObservation (List HtmlElement)

Observe all HTML elements that match the selector provided to Spec.Markup.query.

Spec.Markup.observeElements
  |> Spec.Markup.query << by [ attribute ("data-attr", "some-value") ]
  |> Spec.expect (Spec.Claim.isListWithLength 3)

If no elements match the query, then the subject of the claim will be an empty list.

observeElement : MarkupObservation (Maybe HtmlElement)

Observe an HTML element that matches the selector provided to Spec.Markup.query.

Spec.Markup.observeElement
  |> Spec.Markup.query << by [ attribute ("data-attr", "some-value") ]
  |> Spec.expect (
    Spec.Claim.isSomethingWhere <|
    Spec.Markup.text <|
    Spec.Claim.isEqual Debug.toString "something fun"
  )

Claim that an element is not present in the document like so:

Spec.Markup.observeElement
  |> Spec.Markup.query << by [ id "not-present" ]
  |> Spec.expect Spec.Claim.isNothing

query : ( Selector Selector.Element, MarkupObservation a ) -> Spec.Observer.Observer model a

Search for HTML elements.

Use this function in conjunction with observe, observeElement, or observeElements to observe the HTML document.

Make Claims about an HTML Element


type HtmlElement

Represents an HTML element.

text : Spec.Claim.Claim String -> Spec.Claim.Claim HtmlElement

Claim that the HTML element's text satisfies the given claim.

Spec.Markup.observeElement
  |> Spec.Markup.query << by [ tag "div" ]
  |> Spec.expect (
    Spec.Claim.isSomethingWhere <|
    Spec.Markup.text <|
    Spec.Claim.isStringContaining 1 "red"
  )

Note that an observed HTML element's text includes the text belonging to all its descendants.

attribute : String -> Spec.Claim.Claim (Maybe String) -> Spec.Claim.Claim HtmlElement

Claim that the specified attribute value satisfies the given claim.

Spec.Markup.observeElement
  |> Spec.Markup.query << by [ tag "div" ]
  |> Spec.expect (
    Spec.Claim.isSomethingWhere <|
    Spec.Markup.attribute "class" <|
    Spec.Claim.isSomethingWhere <|
    Spec.Claim.isStringContaining 1 "red"
  )

If you receive an error that the attribute you're interested in is not found, try Spec.Markup.property instead. Elm-spec is examining the actual DOM element, and it's not always clear whether Elm uses the attribute or the associated property to configure the element.

On the difference between attributes and properties, see this.

property : Json.Decode.Decoder a -> Spec.Claim.Claim a -> Spec.Claim.Claim HtmlElement

Apply the given decoder to the HTML element and make a claim about the resulting value.

Use this function to observe a property of an HTML element. For example, you could observe whether a button is disabled like so:

Spec.Markup.observeElement
  |> Spec.Markup.query << by [ tag "button" ]
  |> Spec.expect (
    Spec.Claim.isSomethingWhere <|
    Spec.Markup.property
      (Json.Decode.field "disabled" Json.Decode.bool)
      Spec.Claim.isTrue
  )

Some common properties one might make claims about and the type of the corresponding value:

On the difference between attributes and properties, see this.

Debug

log : ( Selector Selector.Element, Spec.Step.Context model ) -> Spec.Step.Command msg

A step that logs to the console the selected HTML element and its descendants.

Spec.when "the button is clicked twice"
  [ Spec.Markup.target << by [ tag "button" ]
  , Spec.Markup.Event.click
  , Spec.Markup.log << by [ id "click-counter" ]
  , Spec.Markup.Event.click
  ]

If an element is currently targeted, logging a different element does not change the targeted element.

You might use this to help debug a rejected observation.