Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert notes to Remark admonitions #725

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/angular-testing-library/api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -324,9 +324,9 @@ const component = await render(AppComponent)
const componentInstance = component.fixture.componentInstance as AppComponent
```

> 🚨 If you find yourself using `fixture` to access the component's internal
> values you should reconsider! This probable means, you're testing
> implementation details.
:::danger If you find yourself using `fixture` to access the component's
internal values you should reconsider! This probable means, you're testing
implementation details. :::

### `navigate`

Expand Down
6 changes: 3 additions & 3 deletions docs/angular-testing-library/examples.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ title: Examples
sidebar_label: Examples
---

> Read
> [Good testing practices with 🦔 Angular Testing Library](https://timdeschryver.dev/posts/good-testing-practices-with-angular-testing-library)
> for a guided example
:::info Read
[Good testing practices with 🦔 Angular Testing Library](https://timdeschryver.dev/posts/good-testing-practices-with-angular-testing-library)
for a guided example :::

counter.component.ts

Expand Down
10 changes: 5 additions & 5 deletions docs/cypress-testing-library/intro.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@ You can now use all of `DOM Testing Library`'s `findBy`, `findAllBy`, `queryBy`
and `queryAllBy` commands off the global `cy` object.
[See the `DOM Testing Library` docs for reference](https://testing-library.com/docs/dom-testing-library/api-queries).

> Note: the `get*` queries are not supported because for reasonable Cypress
> tests you need retryability and `find*` queries already support that. `query*`
> queries are no longer necessary since v5 and will be removed in v6. `find*`
> fully support built-in Cypress assertions (removes the only use-case for
> `query*`).
:::caution the `get*` queries are not supported because for reasonable Cypress
tests you need retryability and `find*` queries already support that. `query*`
queries are no longer necessary since v5 and will be removed in v6. `find*`
fully support built-in Cypress assertions (removes the only use-case for
`query*`). :::

## With TypeScript

Expand Down
8 changes: 5 additions & 3 deletions docs/dom-testing-library/api-events.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@ title: Firing Events
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

> Most projects have a few use cases for `fireEvent`, but the majority of the
> time you should probably use
> [`@testing-library/user-event`](https://github.com/testing-library/user-event).
:::tip
Most projects have a few use cases for `fireEvent`, but the majority of the
time you should probably use
[`@testing-library/user-event`](https://github.com/testing-library/user-event).
:::

## `fireEvent`

Expand Down
10 changes: 5 additions & 5 deletions docs/dom-testing-library/api-helpers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -57,11 +57,11 @@ module.exports = {
}
```

> **Note**
>
> Custom queries can be added to `React Testing Library`'s `render` method by
> adding `queries` to the options config object. See the render
> [options](react-testing-library/api.mdx#render-options).
:::info
Custom queries can be added to `React Testing Library`'s `render` method by
adding `queries` to the options config object. See the render
[options](react-testing-library/api.mdx#render-options).
:::

## `buildQueries`

Expand Down
138 changes: 74 additions & 64 deletions docs/dom-testing-library/api-queries.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,10 @@ import TabItem from '@theme/TabItem'

## Variants

> `getBy` queries are shown by default in the [query documentation](#queries)
> below.
:::info
`getBy` queries are shown by default in the [query documentation](#queries)
below.
:::

### getBy

Expand Down Expand Up @@ -41,12 +43,12 @@ matches the given query. The promise is rejected if no element is found or if
more than one element is found after a default timeout of `1000`ms. If you need
to find more than one element, then use `findAllBy`.

> **Note**
>
> this is a simple combination of `getBy*` queries and
> [`waitFor`](api-async.mdx#waitfor). The `findBy*` queries accept the `waitFor`
> options as the last argument. (i.e.
> `screen.findByText('text', queryOptions, waitForOptions)`)
:::info
this is a simple combination of `getBy*` queries and
[`waitFor`](api-async.mdx#waitfor). The `findBy*` queries accept the `waitFor`
options as the last argument. (i.e.
`screen.findByText('text', queryOptions, waitForOptions)`)
:::

### findAllBy

Expand Down Expand Up @@ -87,16 +89,16 @@ document.body.innerHTML = exampleHTML
const exampleInput = screen.getByLabelText(/example/i)
```

> **Note**
>
> You need a global DOM environment to use `screen`. If you're using jest, with
> the
> [testEnvironment](https://jestjs.io/docs/en/configuration#testenvironment-string)
> set to `jsdom`, a global DOM environment will be available for you.
>
> If you're loading your test with a `script` tag, make sure it comes after the
> `body`. An example can be seen
> [here](https://github.com/testing-library/dom-testing-library/issues/700#issuecomment-692218886).
:::caution
You need a global DOM environment to use `screen`. If you're using jest, with
the
[testEnvironment](https://jestjs.io/docs/en/configuration#testenvironment-string)
set to `jsdom`, a global DOM environment will be available for you.

If you're loading your test with a `script` tag, make sure it comes after the
`body`. An example can be seen
[here](https://github.com/testing-library/dom-testing-library/issues/700#issuecomment-692218886).
:::

### `screen.debug`

Expand Down Expand Up @@ -143,14 +145,14 @@ screen.logTestingPlaygroundURL(screen.getByText('test'))

## Queries

> **Note**
>
> These queries are the base queries and require you to pass a `container` as
> the first argument. Most framework-implementations of Testing Library provide
> a pre-bound version of these queries when you render your components with them
> which means you do not have to provide a container. In addition, if you just
> want to query `document.body` then you can use the [`screen`](#screen) export
> as demonstrated above (using `screen` is recommended).
:::info
These queries are the base queries and require you to pass a `container` as
the first argument. Most framework-implementations of Testing Library provide
a pre-bound version of these queries when you render your components with them
which means you do not have to provide a container. In addition, if you just
want to query `document.body` then you can use the [`screen`](#screen) export
as demonstrated above (using `screen` is recommended).
:::

### `ByLabelText`

Expand Down Expand Up @@ -256,10 +258,10 @@ If it is important that you query an actual `<label>` element you can provide a
const inputNode = screen.getByLabelText('Username', { selector: 'input' })
```

> **Note**
>
> `getByLabelText` will not work in the case where a `for` attribute on a
> `<label>` element matches an `id` attribute on a non-form element.
:::danger
`getByLabelText` will not work in the case where a `for` attribute on a
`<label>` element matches an `id` attribute on a non-form element.
:::

```js
// This case is not valid
Expand Down Expand Up @@ -321,10 +323,10 @@ cy.findByPlaceholderText('Username').should('exist')
</TabItem>
</Tabs>

> **Note**
>
> A placeholder is not a good substitute for a label so you should generally use
> `getByLabelText` instead.
:::tip
A placeholder is not a good substitute for a label so you should generally use
`getByLabelText` instead.
:::

### `ByText`

Expand Down Expand Up @@ -387,10 +389,10 @@ It also works with `input`s whose `type` attribute is either `submit` or
<input type="submit" value="Send data" />
```

> **Note**
>
> See [`getByLabelText`](#bylabeltext) for more details on how and when to use
> the `selector` option
:::info
See [`getByLabelText`](#bylabeltext) for more details on how and when to use
the `selector` option
:::

The `ignore` option accepts a query selector. If the
[`node.matches`](https://developer.mozilla.org/en-US/docs/Web/API/Element/matches)
Expand Down Expand Up @@ -697,9 +699,11 @@ example, a `button` element can't have the `role` attribute of `heading`,
because the `button` element has default characteristics that conflict with the
`heading` role.

> Roles are matched literally by string equality, without inheriting from the
> ARIA role hierarchy. As a result, querying a superclass role like `checkbox`
> will not include elements with a subclass role like `switch`.
:::caution
Roles are matched literally by string equality, without inheriting from the
ARIA role hierarchy. As a result, querying a superclass role like `checkbox`
will not include elements with a subclass role like `switch`.
:::

You can query the returned element(s) by their
[accessible name](https://www.w3.org/TR/accname-1.1/). The accessible name is
Expand Down Expand Up @@ -786,10 +790,10 @@ you can get the "Sugar" option by calling
state and which elements can have this state see
[ARIA `aria-checked`](https://www.w3.org/TR/wai-aria-1.2/#aria-checked).

> **Note**
>
> Checkboxes have a "mixed" state, which is considered neither checked nor
> unchecked (details [here](https://www.w3.org/TR/html-aam-1.0/#details-id-56)).
:::info
Checkboxes have a "mixed" state, which is considered neither checked nor
unchecked (details [here](https://www.w3.org/TR/html-aam-1.0/#details-id-56)).
:::

#### `pressed`

Expand Down Expand Up @@ -888,11 +892,13 @@ For example, `getByRole('switch')` would always match
`getByRole('checkbox', { queryFallbacks: true })` would enable all fallback
roles and therefore match the same element.

> An element doesn't have multiple roles in a given environment. It has a single
> one. Multiple roles in the attribute are evaluated from left to right until
> the environment finds the first role it understands. This is useful when new
> roles get introduced and you want to start supporting those as well as older
> environments that don't understand that role (yet).
:::info
An element doesn't have multiple roles in a given environment. It has a single
one. Multiple roles in the attribute are evaluated from left to right until
the environment finds the first role it understands. This is useful when new
roles get introduced and you want to start supporting those as well as older
environments that don't understand that role (yet).
:::

#### `level`

Expand Down Expand Up @@ -938,8 +944,10 @@ headings `<h1>-<h6>`.
To learn more about the `aria-level` property, see
[ARIA `aria-level`](https://www.w3.org/TR/wai-aria-1.2/#aria-level).

> The `level` option is _only_ applicable to the `heading` role. An error will
> be thrown when used with any other role.
:::danger
The `level` option is _only_ applicable to the `heading` role. An error will
be thrown when used with any other role.
:::

### `ByTestId`

Expand Down Expand Up @@ -993,13 +1001,15 @@ cy.findByTestId('custom-element').should('exist')
</TabItem>
</Tabs>

> In the spirit of [the guiding principles](guiding-principles.mdx), it is
> recommended to use this only after the other queries don't work for your use
> case. Using data-testid attributes do not resemble how your software is used
> and should be avoided if possible. That said, they are _way_ better than
> querying based on DOM structure or styling css class names. Learn more about
> `data-testid`s from the blog post
> ["Making your UI tests resilient to change"](https://kentcdodds.com/blog/making-your-ui-tests-resilient-to-change)
:::caution
In the spirit of [the guiding principles](guiding-principles.mdx), it is
recommended to use this only after the other queries don't work for your use
case. Using data-testid attributes do not resemble how your software is used
and should be avoided if possible. That said, they are _way_ better than
querying based on DOM structure or styling css class names. Learn more about
`data-testid`s from the blog post
["Making your UI tests resilient to change"](https://kentcdodds.com/blog/making-your-ui-tests-resilient-to-change)
:::

#### Overriding `data-testid`

Expand Down Expand Up @@ -1042,11 +1052,11 @@ If you want to prevent that normalization, or provide alternative normalization
function in the options object. This function will be given a string and is
expected to return a normalized version of that string.

> **Note**
>
> Specifying a value for `normalizer` _replaces_ the built-in normalization, but
> you can call `getDefaultNormalizer` to obtain a built-in normalizer, either to
> adjust that normalization or to call it from your own normalizer.
:::info
Specifying a value for `normalizer` _replaces_ the built-in normalization, but
you can call `getDefaultNormalizer` to obtain a built-in normalizer, either to
adjust that normalization or to call it from your own normalizer.
:::

`getDefaultNormalizer` takes an options object which allows the selection of
behaviour:
Expand Down
19 changes: 9 additions & 10 deletions docs/dom-testing-library/cheatsheet.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -85,16 +85,15 @@ See [Async API](dom-testing-library/api-async.mdx). Remember to `await` or
- **waitForElementToBeRemoved** (Promise) retry the function until it no longer
returns a DOM node

> **Deprecated since v7.0.0:**
>
> - **wait** (Promise) retry the function within until it stops throwing or
> times
> - **waitForElement** (Promise) retry the function until it returns an element
> or an array of elements
> - `findBy` and `findAllBy` queries are async and retry until either a timeout
> or if the query returns successfully; they wrap `waitForElement`
> - **waitForDomChange** (Promise) retry the function each time the DOM is
> changed
:::danger Deprecated since v7.0.0

- **wait** (Promise) retry the function within until it stops throwing or times
- **waitForElement** (Promise) retry the function until it returns an element or
an array of elements
- `findBy` and `findAllBy` queries are async and retry until either a timeout or
if the query returns successfully; they wrap `waitForElement`
- **waitForDomChange** (Promise) retry the function each time the DOM is changed
:::

## Events

Expand Down
8 changes: 4 additions & 4 deletions docs/ecosystem-jasmine-dom.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,10 @@ expect(screen.queryByTestId('not-empty')).not.toBeEmptyDOMElement()
expect(screen.getByText('Visible Example')).toBeVisible()
```

> Note: when using some of these matchers, you may need to make sure you use a
> query function (like `queryByTestId`) rather than a get function (like
> `getByTestId`). Otherwise the `get*` function could throw an error before your
> assertion.
:::caution When using some of these matchers, you may need to make sure you use
a query function (like `queryByTestId`) rather than a get function (like
`getByTestId`). Otherwise the `get*` function could throw an error before your
assertion. :::

Check out [jasmine-dom's documentation][gh] for a full list of available
matchers.
Expand Down
8 changes: 4 additions & 4 deletions docs/ecosystem-jest-dom.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,10 @@ test('uses jest-dom', () => {
})
```

> Note: when using some of these matchers, you may need to make sure you use a
> query function (like `queryByTestId`) rather than a get function (like
> `getByTestId`). Otherwise the `get*` function could throw an error before your
> assertion.
:::caution When using some of these matchers, you may need to make sure you use
a query function (like `queryByTestId`) rather than a get function (like
`getByTestId`). Otherwise the `get*` function could throw an error before your
assertion. :::

Check out [jest-dom's documentation][gh] for a full list of available matchers.

Expand Down
8 changes: 4 additions & 4 deletions docs/ecosystem-jest-native.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,10 @@ expect(queryByTestId(baseElement, 'not-empty')).not.toBeEmpty()
expect(getByText(baseElement, 'Visible Example')).toBeVisible()
```

> Note: when using some of these matchers, you may need to make sure you use a
> query function (like `queryByTestId`) rather than a get function (like
> `getByTestId`). Otherwise the `get*` function could throw an error before your
> assertion.
:::caution When using some of these matchers, you may need to make sure you use
a query function (like `queryByTestId`) rather than a get function (like
`getByTestId`). Otherwise the `get*` function could throw an error before your
assertion. :::

Check out
[Jest Native's documentation](https://github.com/testing-library/jest-native)
Expand Down
Loading