Proposal: introducing CSS Selector Helpers

[germsvel]

I've been thinking of adding a set of CSS Selector helpers (for lack of a better word) that help in cases like #44 and #27.

Now I have a working prototype, but I'd like to make sure I'm covering all the existing cases.

It would work something like this:

conn
|> visit("/")
|> assert_has(within("#user", ".likes-count"), "23")

The within/2 helper in that case would resolve into a CSS selector: #user .likes-count.

That means the underlying assert_has/3 functionality still relies on CSS selectors for assertions. I like that. It leaves the option open and flexible for people to use.

For some helpers, we'd can do something a bit more complex by adjusting assert_has to also take data structures that can then be transformed into strings.

For example, if we want to handle case #44 where we're targeting inputs by their label, I tested the following in. my prototype:

# ...
|> assert_has(input(labeled_by: "Name", value: "Jeff"))

That input/1 helper would first find a label with text "Name", look for its for attribute (suppose it's user-name) and then generate a CSS selector like this: input#user-name[value="Jeff"]

What should we cover?

And I'd also love to know if we should be covering. So far, I'm thinking:

• within: helpful for generating descendant selectors
• input: covers Devise a way to find form inputs by their associated labels #44 and is helpful when trying to test the contents of an input
• data: easier to write data-role or data-testid when needed
• nth_child: covers Add an assertion helper for checking an element's children #27 and helpful if you care about the order of the children (e.g. nth_child("#table", "tr", 2) or maybe child("#table, "tr", n: 2)

Open questions

• If we introduce these helpers, it would be nice if they worked with other PhoenixTest helpers besides assert_has/refute_has. For example, it'd be nice to do click_button(within(...), "Save"). But I haven't tested that out in my prototype yet.

I'm open to suggestions/thoughts on what people think about the feel or ergonomics of the approach outlined above.

[mattwynne]

I like where this is heading. It reminds me of the hamcrest family of assertion libraries, which I'm a big fan of because they're so composable.

So I wonder if you can do something similar here, where assert_has and refute_has work with two things: a selector and a matcher.

For example, input(labelled: "Username") would be a selector, and has_value("matt") would be a matcher:

assert_that(input(labelled: "Username"), has_value("matt"))

This is also along the lines of the Ruby library Capybara, which offers a bunch of selectors and matchers.

[germsvel]

This has now been superseded by improvements to assert_has and refute_has that take :count, :at as options. We still need to figure out how to target elements by label but that can be tracked on #44