From cc6659382758b68349942087b3b316f2d005e928 Mon Sep 17 00:00:00 2001 From: Sebastian Silbermann Date: Mon, 20 Jul 2020 19:23:31 +0200 Subject: [PATCH 1/4] Remove references to /core/test- --- docs/src/pages/guides/testing/testing.md | 149 ----------------------- 1 file changed, 149 deletions(-) diff --git a/docs/src/pages/guides/testing/testing.md b/docs/src/pages/guides/testing/testing.md index 17cfee003e2f81..e0fb3c85f7a5e8 100644 --- a/docs/src/pages/guides/testing/testing.md +++ b/docs/src/pages/guides/testing/testing.md @@ -16,152 +16,3 @@ What about writing tests in userspace? The Material-UI styling infrastructure us We use almost exclusively full DOM rendering APIs. We encourage you to do the same especially if your components rely on custom themes. Tests using shallow rendering APIs become more brittle with the amount of provider components they require. - -### Full DOM rendering - -Full DOM rendering is ideal for use cases where you have components that may interact with DOM APIs or may require the full lifecycle in order to fully test the component (e.g., `componentDidMount` etc.). - -The `createMount()` function is provided for this situation. -Aside from wrapping the enzyme API, it provides a `cleanUp` function. - -### Shallow rendering - -Shallow rendering is useful to constrain your testing to a component as a unit. This also ensures that your tests aren't indirectly asserting behavior of child components. -Shallow rendering was created to test components in isolation. This means without leaking child implementation details such as the context. - -The `createShallow()` function can be used for this situation. Aside from wrapping the enzyme API, it provides a `dive` and `untilSelector` option. - -### Render to string - -Rendering to a string is useful to test the behavior of the components that are used on the server. -You can take advantage of this to assert the generated HTML string. - -The `createRender()` function is ideal for this. This is just an alias for the enzyme API, which is only exposed for consistency. - -## API - -### `createMount([options]) => mount` - -Generate an enhanced mount function with the needed context. -Please refer to the [enzyme API documentation](https://airbnb.io/enzyme/docs/api/mount.html) for further details on the `mount` function. - -#### Arguments - -1. `options` (_Object_ [optional]) - -- `options.mount` (_Function_ [optional]): The mount function to enhance, it uses **enzyme by default**. -- The other keys are forwarded to the options argument of `enzyme.mount()`. - -#### Returns - -`mount` (_mount_): A mount function. - -#### Examples - -```jsx -import { createMount } from '@material-ui/core/test-utils'; -import { ThemeProvider } from '@material-ui/core/styles'; - -describe('', () => { - let mount; - - function MySuccessButton({ children }) { - return ( - - {children} - - ); - } - - before(() => { - mount = createMount(); - }); - - after(() => { - mount.cleanUp(); - }); - - it('should work', () => { - const wrapper = mount( - - - , - ); - }); -}); -``` - -### `createShallow([options]) => shallow` - -Generate an enhanced shallow function with the needed context. -Please refer to the [enzyme API documentation](https://airbnb.io/enzyme/docs/api/shallow.html) for further details on the `shallow` function. - -#### Arguments - -1. `options` (_Object_ [optional]) - -- `options.shallow` (_Function_ [optional]): The shallow function to enhance, it uses **enzyme by default**. -- `options.untilSelector` (_String_ [optional]): Recursively shallow renders the children until it can find the provided selector. It's useful to drill down higher-order components. -- `options.dive` (_Boolean_ [optional]): Shallow function renders the one non-DOM child of the current wrapper, and returns a wrapper around the result. -- The other keys are forwarded to the options argument of `enzyme.shallow()`. - -#### Returns - -`shallow` (_shallow_): A shallow function. - -#### Examples - -```jsx -import { createShallow } from '@material-ui/core/test-utils'; - -describe('', () => { - let shallow; - - before(() => { - // This is Mocha; in Jest, use beforeAll - shallow = createShallow(); - }); - - it('should work', () => { - const wrapper = shallow(); - }); -}); -``` - -### `createRender([options]) => render` - -Generate a render to string function with the needed context. -Please refer to the [enzyme API documentation](https://airbnb.io/enzyme/docs/api/render.html) for further details on the `render` function. - -#### Arguments - -1. `options` (_Object_ [optional]) - -- `options.render` (_Function_ [optional]): The render function to enhance, it uses **enzyme by default**. -- The other keys are forwarded to the options argument of `enzyme.render()`. - -#### Returns - -`render` (_Function_): A render to string function. - -#### Examples - -```jsx -import { createRender } from '@material-ui/core/test-utils'; - -describe('', () => { - let render; - - before(() => { - render = createRender(); - }); - - it('should work', () => { - const wrapper = render(); - }); -}); -``` From 75b0e7a1bd62ce463a984b8dc885808ca2b357b7 Mon Sep 17 00:00:00 2001 From: Sebastian Silbermann Date: Mon, 20 Jul 2020 19:23:58 +0200 Subject: [PATCH 2/4] Move "Internal" last it's least interesting for a user. more a nice-to-know --- docs/src/pages/guides/testing/testing.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/src/pages/guides/testing/testing.md b/docs/src/pages/guides/testing/testing.md index e0fb3c85f7a5e8..db8a775cf5d754 100644 --- a/docs/src/pages/guides/testing/testing.md +++ b/docs/src/pages/guides/testing/testing.md @@ -4,15 +4,15 @@ Examples in this guide use [global methods from Mocha](https://mochajs.org/api/global.html), not [Jest](https://jestjs.io/docs/en/api). -## Internal - -Material-UI has **a wide range** of tests so we can -iterate with confidence on the components, for instance, the visual regression tests provided by [Argos-CI](https://www.argos-ci.com/mui-org/material-ui) have proven to be really helpful. -To learn more about the internal tests, you can have a look at the [README](https://github.com/mui-org/material-ui/blob/next/test/README.md). - ## Userspace What about writing tests in userspace? The Material-UI styling infrastructure uses some helper functions built on top of [enzyme](https://github.com/airbnb/enzyme) to make the process easier, which we are exposing. You can take advantage of them if you so choose. We use almost exclusively full DOM rendering APIs. We encourage you to do the same especially if your components rely on custom themes. Tests using shallow rendering APIs become more brittle with the amount of provider components they require. + +## Internal + +Material-UI has **a wide range** of tests so we can +iterate with confidence on the components, for instance, the visual regression tests provided by [Argos-CI](https://www.argos-ci.com/mui-org/material-ui) have proven to be really helpful. +To learn more about the internal tests, you can have a look at the [README](https://github.com/mui-org/material-ui/blob/next/test/README.md). From a220764c693140b502274486529ba8b5635f03d4 Mon Sep 17 00:00:00 2001 From: Sebastian Silbermann Date: Mon, 20 Jul 2020 19:44:36 +0200 Subject: [PATCH 3/4] [docs] Update testing guide --- docs/src/pages/guides/testing/testing.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/src/pages/guides/testing/testing.md b/docs/src/pages/guides/testing/testing.md index db8a775cf5d754..59dcf1189401de 100644 --- a/docs/src/pages/guides/testing/testing.md +++ b/docs/src/pages/guides/testing/testing.md @@ -2,14 +2,17 @@

Write tests to prevent regressions and write better code.

-Examples in this guide use [global methods from Mocha](https://mochajs.org/api/global.html), not [Jest](https://jestjs.io/docs/en/api). - ## Userspace -What about writing tests in userspace? The Material-UI styling infrastructure uses some helper functions built on top of [enzyme](https://github.com/airbnb/enzyme) to make the process easier, which we are exposing. You can take advantage of them if you so choose. -We use almost exclusively full DOM rendering APIs. We encourage you to do the same especially -if your components rely on custom themes. Tests using shallow rendering APIs become more brittle -with the amount of provider components they require. +We recommend testing your application without tying the tests too close to Material-UI. +This is how we test our components internally. +A library that has a first-class API for this approach is [`@testing-library/react`](https://testing-library.com/docs/react-testing-library/intro). + +For example, when rendering a `TextField` your test should not need to query for the specific Material-UI instance of the `TextField` but rather for the `input`, or the `[role="textbox"]`. + +By not relying on the React component tree you make your test more robust against internal changes in Material-UI or, if you need snapshot testing, adding additional wrapper components such as context providers. +Though we don't recommend snapshot testing. +["Effective snapshot testing" by Kent C. Dodds](https://kentcdodds.com/blog/effective-snapshot-testing) goes into more details why snapshot testing might be misleading for React component tests. ## Internal From 07a8acfba6aef9e2e402879d80f91d8eaf2803a7 Mon Sep 17 00:00:00 2001 From: Sebastian Silbermann Date: Tue, 21 Jul 2020 07:44:47 +0200 Subject: [PATCH 4/4] Matt's review (partial) Co-authored-by: Matt --- docs/src/pages/guides/testing/testing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/src/pages/guides/testing/testing.md b/docs/src/pages/guides/testing/testing.md index 59dcf1189401de..50903f5f31defc 100644 --- a/docs/src/pages/guides/testing/testing.md +++ b/docs/src/pages/guides/testing/testing.md @@ -4,14 +4,14 @@ ## Userspace -We recommend testing your application without tying the tests too close to Material-UI. -This is how we test our components internally. +It's generally recommended to test your application without tying the tests too closely to Material-UI. +This is how Material-UI components are tested internally. A library that has a first-class API for this approach is [`@testing-library/react`](https://testing-library.com/docs/react-testing-library/intro). -For example, when rendering a `TextField` your test should not need to query for the specific Material-UI instance of the `TextField` but rather for the `input`, or the `[role="textbox"]`. +For example, when rendering a `TextField` your test should not need to query for the specific Material-UI instance of the `TextField` but rather for the `input`, or `[role="textbox"]`. By not relying on the React component tree you make your test more robust against internal changes in Material-UI or, if you need snapshot testing, adding additional wrapper components such as context providers. -Though we don't recommend snapshot testing. +We don't recommend snapshot testing though. ["Effective snapshot testing" by Kent C. Dodds](https://kentcdodds.com/blog/effective-snapshot-testing) goes into more details why snapshot testing might be misleading for React component tests. ## Internal