search

testing-library / dom-testing-library

🐙 Simple and complete DOM testing utilities that encourage good testing practices.
https://testing-library.com/dom
MIT License
3.27k stars 466 forks source link

Feature request: Shadow DOM support #413

Open apalaniuk opened 4 years ago

apalaniuk commented 4 years ago

Describe the feature you'd like:

Web components are an increasingly popular way of creating reusable elements. Due to the existence of shadow DOM, user-focused testing is more difficult and requires tooling focused around the issue, as in the most permissive case, element queries/observer events (eg. via MutationObservers) stop at shadow boundaries and must explicitly be projected into shadow trees. Without support from tooling, aspects of a web app written using web components are virtually untestable without using methods contrary to the goals of this project.

Suggested implementation:

Describe alternatives you've considered:

I'd be happy to add this feature, and support for basic functionality (query, waits) was straightforward to implement, but I wanted to get insight on constraints/concerns in advance as I don't currently use this library.

ashubham commented 4 years ago

+1

It will be great to build support for WebComponent based frameworks like lit-element. If there is a adapter/plugin API, I am sure the community will jump on to build it.

alexkrolick commented 4 years ago

How much of this depends on JSDOM itself? This library doesn't implement the DOM part, just traversal.

apalaniuk commented 4 years ago

Hi @alexkrolick, it's a good question. JSDOM currently has shadow DOM support, with a few restrictions. The largest issue for testing right now is that this is almost entirely used in the context of web components, and support for custom elements is in-flight (https://github.com/jsdom/jsdom/pull/2548).

That said, the only changes required in here for shadow DOM support should be unrelated, since this would just need to support automatically traversing through shadow trees for queries/attaching MutationObservers/etc, and shadow roots can be attached to many standard elements.

Since the overall change seems small, it's probably better to just implement in a fork and get more direct feedback based on an implementation.

kentcdodds commented 4 years ago

A PR would be helpful. But I'm getting the impression this will be anything but a small change 😬

ashubham commented 4 years ago

What about when we use this library with puppeteer ? How difficult will be to have webcomponent support in that mode ?

apalaniuk commented 4 years ago

@kentcdodds There's definitely a lot of complexity to work out, so I'm just being (overly) optimistic 🙂 we have done similar things at my company in the past (though only supporting a subset of the required operations), but supporting it for general use cases will take some thought (complexity to get same behaviour in traversing the light DOM given there aren't any primitives for traversal/element selection when considering shadow DOM, performance, maintainability, providing unsurprising behaviour in all cases, etc.)

Westbrook commented 4 years ago

I've been toying with an approach to making this possible: https://github.com/adobe/spectrum-web-components/pull/420

For me, there are two issues in particular that I'm working on: 1) ES Module based support so that Karma + es-dev-server can run @testing-library/dom which has some downstream CJS dependencies, for which I'm rebuilding the project locally: https://github.com/adobe/spectrum-web-components/pull/420/files#diff-de467343944f9302cd195062f4d866b2 it also knocks off some Node vs browser differences 2) Seeing into shadow DOM appropriately (normally an anti-pattern, but acceptable, IMO, in a testing environment), for which I'm using: https://github.com/adobe/spectrum-web-components/pull/420/files#diff-33d340131f49793bce88e37a2122f57c

At the intersection between the two issues is shimming @testing-library/dom to use the non-standard querySelectorAllWithShadowDOM so that the "available" DOM is queried without altering the API of the components.

Is this looking completely crazy? Are either or both of these changes something that might look interesting in a PR here?

Westbrook commented 4 years ago

So, in a way, the above is also a bit of a revival of #161 as well... 😬

kentcdodds commented 4 years ago

Hi folks,

I just am not convinced that the complexity will be worth it. You can feel free to open a PR if you like, but if it's more than a little complex I don't think I'll want it here and instead maybe you could add a custom query and even make a library of those for the people using Shadow DOM.

Westbrook commented 4 years ago

Definitely the steps for full web component support could be more complex, but ensuring that DOM targetted code can actually be tested in a real DOM environment would be a great baseline for this library to support. Then, were someone to want to extend/alter it to better support the growing capabilities of the full DOM model itself they could so with little difficulty. To that end, I think the initial steps that I'd love to see are as follows:

The best solution is to PR the library to export ESM on its own (if you were willing to support an issue/PR of that there, the voice of such a well-used and respected library would likely go a long way, so I'd be happy to open the conversation for you to jump in there), but as we've seen not everyone is excited about supporting modern APIs in their libraries. In the interim of that occuring, I'd like to pre-process @sheerun/mutationobserver-shim via an addition to the Rollup config similar to (output locations TBD, etc, etc):

    {
        input: require.resolve(
            '@sheerun/mutationobserver-shim/MutationObserver.js'
        ),
        output: {
            file: './lib/mutationobserver-shim/index.js',
            format: 'es',
        },
        plugins: [
            resolve({
                browser: true,
                preferBuiltins: false,
            }),
            commonjs(),
        ],
    },

Then it's a simple alias to slot this new output into @test-library/dom without having to affect the current contents of the JS (meaning it's plug&play when the upstream output changes!). This looks like:

            alias({
                entries: {
                    '@sheerun/mutationobserver-shim':
                        'lib/mutationobserver-shim/index.js',
                },
            }),

With these two changes, it is likely that #161 could be reopened/closed as fixed in one fell swoop and then we could have a stand-alone conversation about supporting the web component specifications. The decision as to whether that could be achieved via custom queries or should belong in @test-library/dom, in an alternate @test-library/full-dom sort of package, or be supported via an external extension of the library is an important one and should be given the focused consideration that it deserves.

Thanks in advance for your gracious insight.

kentcdodds commented 4 years ago

Is there any chance that you could maintain a separate package that extends the capabilities here (via custom queries or similar)? If so, I would be willing to make a few smaller modifications (like the process PR I just merged of yours [thank you]) to make that easier. What do you think?

apalaniuk commented 4 years ago

I haven't been able to revisit this at all, but I definitely appreciate the work others have done. I was thinking over the holidays that the relative complexity of the implementation as it trends toward "reasonable behaviour" in ways the specs don't define + possible performance implications + the relatively few users that need this in the near term means that it would likely be best as a separate package/plugin.

Westbrook commented 4 years ago

Thanks for your thoughts here. I wouldn't be opposed to that, to support that path requiring as few modifications as possible could you share a little more on the following point?

As per https://github.com/testing-library/dom-testing-library/issues/348#issuecomment-576824315 it seems like newer versions of JSDom will have caught up with browser specs as far as MutationObservers (Can I Use). That being so, do you foresee a future where you removed the @sheerun/mutationobserver-shim dependency from this library? I suppose that would technically be a breaking change, but it would prevent from needing to alter its output either at the repo level, where the project seems complete (beyond simply not accepting issues), or at the project level, via Rollup configs as outlined above.

With that change a separate package would only need to do:

replace({
    querySelectorAll: 'querySelectorAllWithShadowDOM',
}),

and put the library behind the shim for querySelectorAllWithShadowDOM which would be a dream to maintain on my end. Thanks for helping me talk through this possibilities here!

kentcdodds commented 4 years ago

Hi @Westbrook,

I definitely have plans to remove that shim in the next breaking change (which is hopefully coming soon).

Sounds like once we get that done then you'll be in a pretty good place to make a simple package that supports shadow DOM which I think is the best path forward 👍

I'll be sure to ping you all in here when we've published the update. You're more than welcome to participate in discussion leading up to that major version bump. Hopefully that'll start in the next few days.

kentcdodds commented 4 years ago

:tada: This issue has been resolved in version 7.0.0-beta.3 :tada:

The release is available on:

Your semantic-release bot :package::rocket:

kentcdodds commented 4 years ago

:tada: This issue has been resolved in version 7.0.0 :tada:

The release is available on:

Your semantic-release bot :package::rocket:

stevematney commented 4 years ago

@Westbrook we're using dom-testing-library to test some Web Components, and would love to see our approach simplified by a package like the one you mentioned potentially creating. Do you have any plans to release something like that?

Westbrook commented 4 years ago

Sorry, I let this fall way way way off my to-do list, but finally got around to pushing a beta release of the wrapper I'd been working with to NPM: https://www.npmjs.com/package/testing-library__dom Hopefully it'll be useful for people!

kentcdodds commented 4 years ago

Thanks!

umpox commented 4 years ago

Might be helpful to post a different solution to querying elements in a shadow root, if anyone else is reading this:

If are able to access the shadow root (e.g. query the an element that wraps it), you can just do something like this:

    const { queryByText } = within(someNode.shadowRoot);
    queryByText('Element within a shadow root!');
renet commented 3 years ago

There seems to be no real documentation on the testing-library__dom package. And there was no update for 8 months now and the package is still in beta.

I consider web components a standard for all modern browsers. Wouldn't it make sense to add full support for shadow DOM and web components directly to the DOM Testing Library?

ashleyryan commented 2 years ago

With React 18 adding support for web components behind the experimental flag, I'm wondering if testing-library has given any more thought to officially supporting the shadow dom.

@Westbrook has done some great work providing a third party library, but it's not official, poorly documented, and the NPM page for it links to the Spectrum Web Components github, not the lib directly.

More and more web component based design systems are being released using Lit or Stencil. Both frameworks provide react wrappers, but with React 18 they no longer will have to.

kentcdodds commented 2 years ago

I think you're right Ashley... We probably should build in support for Shadow DOM. As I'm no longer an active maintainer though it's not my decision. But I think it's probably the right one at this point.

wbern commented 2 years ago

@kentcdodds who's the maintainer now?

kentcdodds commented 2 years ago

There's a great team of people who are maintaining the Testing Library repositories. You can check who's most recently made changes by looking at the contributing graph: https://github.com/testing-library/dom-testing-library/graphs/contributors?from=2021-08-06&to=2022-03-31&type=c

KonnorRogers commented 2 years ago

Working on adding tests for it, but I created a shadow DOM inspection library with a "shadow" for DOM Testing library. Still very new and need to run the paces on it.

https://github.com/ParamagicDev/shadow-dom-testing-library

treshugart commented 2 years ago

Is this issue talking about being able to screen.getByText('something in a shadow root') (or on an ancestor node) and have it just work for descendant shadow roots?

That would probably be a serious lift and I don't think it makes sense, either, because then you'd be testing implementation details of a component down the tree. Currently, queries will run and find light dom which should suffice.

However, when directly testing a web component that has a shadow root, there issues:

Awaiting a shadowRoot attachment

For every component that you want to test, the upgrading and shadow root attachment may happen asynchronously on the next event loop. For this reason, one must do something like:

async function waitForShadowRoot(host) {
  return await waitFor(() => {
    if (!host.shadowRoot) {
      throw new Error(`Host does not have a shadow root.\n\n${prettyDOM(host)}`)
    }
  })
}

Binding queries to the shadowRoot

You can use within(shadowRoot) to bind queries to it and it works. However, if using TypeScript, the type expected by within is HTMLElement so you must do within((shadowRoot as unknown) as HTMLElement). I'm unsure of the ramifications of making this more permissible but it seems doing DocumentFragment | Element may be ok, at least on the surface.

prettyDOM and prettyFormat (from Jest)

Things work fine if there are no assertion errors. However, if there are, when the error messages are being formatted with prettyDOM and prettyFormat, these functions have issues understanding a node of type DocumentFragment (ShadowRoot inherits from DocumentFragment) because they use outerHTML and prettyFormat doesn't understand it (but does work with a NodeList). I got this working pretty quickly by:

These could be made more robust by checking if dom is a DocumentFragment first, and then using the alternatives only if it is.

I'm happy to attempt a PR for this, but I'd like to see what others think first before spending time on something that may potentially not make its way in.

Thanks! Thoughts?

alexkrolick commented 2 years ago

Is this issue talking about being able to screen.getByText('something in a shadow root') (or on an ancestor node) and have it just work for descendant shadow roots?

That's what Cypress (and Playwright) seem to do when you have the "pierce Shadow DOM" mode on, but I think it breaks the intended encapsulation a bit too much. I think a better solution is more like what you're describing, where entering the shadow root is explicit.

EDIT: I could see the default being to enter the Shadow DOM by default though, since users shouldn't have to know the difference.

<h1>Login</h1>
<login-form>
  <input aria-label="Email" />
</login-form>
const emailInput = await findByRole("input", { name: "Email" }) // this is a light dom child element
const submitButton = await within(await findByRole('form'), { shadow: true }) // entering the shadow dom
  .findByRole('button', {name: "Submit"}) // something in the shadow dom

You can use within(shadowRoot) to bind queries to it and it works.

Question - is that due to how JSDOM implements Shadow DOM or does it work in browsers too?

treshugart commented 2 years ago

I could see the default being to enter the Shadow DOM by default though, since users shouldn't have to know the difference.

Of course, my suggestion does break the ability to have "far reaching" integration tests, but these concepts ("piercing" and my proposed idea) aren't mutually exclusive. In fact, the latter complements the former and could also be considered a prerequisite.

You could go as far to say that if your test depends on being able to locate something in a shadow root of a descendant, that it's likely what you're trying to locate should either be passed via light DOM or you should be testing it in another way, such as the existence of an attribute on the descendant host. The tests for the descendant may best be left to the responsibility of that component.

A good example of this are built-in elements such as <input />. There's no way of knowing how it is implemented. Instead, we test by way of attributes, properties and events. It just so happens that with custom elements, we can see into the shadow root if we want, but just because we can does not mean we should.

Question - is that due to how JSDOM implements Shadow DOM or does it work in browsers too?

I'm unsure if you're asking about the within API or about shadow DOM behavior? The within function is a @testing-library/dom API that binds the getBy*, findBy* and queryBy* functions to a particular node. JSDOM implements shadow DOM the same way a browser would and therefore behaves the same way.

alexkrolick commented 2 years ago

JSDOM implements shadow DOM the same way a browser would and therefore behaves the same way.

That's what I wanted to confirm. There can be some implementation differences.

A good example of this are built-in elements such as . There's no way of knowing how it is implemented. Instead, we test by way of attributes, properties and events.

That is true but it represents a single node. A more complex component like a video player may have multiple interactive inner elements that implement various aria roles.

treshugart commented 2 years ago

A more complex component like a video player may have multiple interactive inner elements that implement various aria roles.

I see what you're saying but it doesn't change much about how we'd integration test it. Said video player should have tests of its own for its implementation details.

Similarly, composite trees such as lists and tables may have their individual elements composed of smaller pieces, but we can't test those because they're hidden to the outside world. We can, however access, a tr in a table, which would be similar to what we call light dom in custom composite elements.

Being able to see into the trees of descendant elements is convenient but it doesn't mean that it's necessarily a good thing. I often find in my own experiences that it makes testing more brittle to rely on such behavior.

ashleyryan commented 2 years ago

As a react consumer of a web-component based component library, some recurring issues where I've run into not being able to access things in the shadow DOM have often-times involved an X/close button - where a modal, or alert, or other component render the X button button in the shadow dom, instead of being passed into the components via the light dom. But I need to be able to click it to test an interaction.

If the intent of testing-library is to be able to test an app like a user would, then the shadow dom is irrelevant - there is no distinction to users.

However, because of the recursive nature of traversing the shadow dom, and because the shadow dom is not intended to be a public API, I think it's reasonable to not having it enabled by default.

treshugart commented 2 years ago

As a react consumer of a web-component based component library, some recurring issues where I've run into not being able to access things in the shadow DOM have often-times involved an X/close button

That's a super valid point and there are many similar use cases. The only thing I could think of right now - that isn't as easy, for sure - would be to use fireEvent.click(within(getByText('text in modal light DOM').shadowRoot).findByText('close')) or similar. At the very least, it's explicit and we can rely on shadowRoot being publicly available on the element.

alexkrolick commented 2 years ago

I've been using Web Components and I'd like to figure out how we can move forward with this. I'll start by listing some blockers with current workarounds:

  1. PrettyDOM doesn't understand shadowRoot (it extends Node and DocumentFragment so it should work). This prevents error messages from being usable.
prettyDOM(element.shadowRoot)
//     TypeError: Expected an element or document but got ShadowRoot
  1. within(el.shadowRoot).getByText() workaround isn't recursive. This new package shadow-dom-testing-library seems to be queries that recursively search in shadow roots, if found. This could be a good solution to figure out how to add to core.
KonnorRogers commented 2 years ago

@alexkrolick just don't look too closely at the source. Some maniac is out here patching the ShadowRoot prototype to trick PrettyDOM...

https://github.com/KonnorRogers/shadow-dom-testing-library/blob/5029048b332d46acf5f3875a54a76d2a509cb2e0/src/index.ts#L33

my main concern is that many of these queries may start behaving differently than expected when they start recursing through shadowRoots especially in regards to "ids" and other unique attributes. This is why I added a "Shadow" prefix so as not to break the behavior of existing queries.

alexkrolick commented 2 years ago

@KonnorRogers thanks for the info. I created #1188 to track the prettyDOM changes separately. Ideally we could remove outerHTML patch.

Regarding your library, have you considering packaging it as a set of custom queries rather than an extended screen import? This may make the package more compatible with other custom extensions.

https://testing-library.com/docs/react-testing-library/setup#add-custom-queries

KonnorRogers commented 2 years ago

@alexkrolick I don't believe this is the best place to discuss this. There's a lot of people attached to this. If you want to open an issue on the repo itself you're more than welcome to. All that said, I do agree It may be worth providing an entrypoint only for specific queries, and then the overriden screen as a seperate entrypoint.