[Portal API] Impossible to verify interaction based on successful toast messages displayed outside the current section container

[khamusa]

Within a section, we'd like to verify a given text string is displayed in a toast. Given the toast is a floating UI element, it's placed outside the section hierarchy in the DOM, so our precondition methods do not work.

Example:

def update_home_address(**address)
    within(home_address) do
      find("button", text: "Edit").click

      fill_address_form(**address)
    end

    # Does not work: the toast is not inside this container
    has_content!("Your home address has been updated")
 end

The solution we're looking for should allow section objects to perform limited assertions outside their container scope. We automatically scope all capybara's methods for a reason, and we do not want to provide easy ways to bypass this mechanism. Instead, a solution for this should make it rather explicit that this violation of the DOM hierarchy is taking place.

The most naive option, which does not fully satisfy the above, would be to allow bypassing the automatic DOM scoping:

unscoped { has_content!(...) } # or
unscoped.has_content!(...)

The above is very explicit, but would also mean giving green light for people to write unscoped code at will within their page objects. So this is explicit and easy, but we want explicit and difficult. - or am I overthinking this?

[khamusa]

Here's an idea. Suppose we have a section such as the one below:

# toast_message_container is outside the parent section container
portal_section :toast_message, test_id: :toast_message_container do
  # ...
end

Trying to use it would cause an error, though, unless the :toast_message_container test_id were explicitly whitelabeled in the gem config in an initializer:

Oyster::Harbor.config do |config|
  config.portal_sections = %i[toast_message_container ...]
end

Using the word portal here as a reference to react's concept of portal which allows a given component to render stuff in a dom element that is not its child...

This already adds an extra obstacle that makes it harder to abuse unscoping. Then, this initializer file could be code-owned by a specialized team that would be able to keep under control attempts to use unsceoped section. We'd also have to impose the config object can't be extended later, though...

[khamusa]

Another use case: the calendar element used to select a date for datepickers is also rendered as a react portal. What these features have in common is that they're rendered within a div element in the root of the html with thedata-floating-ui-portal attribute set.

I think reflecting react's concept of portal in the framework might be a good idea, so more generally:

portal_section :datepicker

This would create a datepicker section within the current page/section object, but it would always match the data-floating-ui-portal element, not tied to the parent component dom structure. Given this would not allow any other testid to be used, this would not open a precedent for undiscriminated usage.

The main issue is that this is not a generic requirement we could embed within the framework...