diff --git a/docs/api.md b/docs/api.md index a389c17..37cf6cf 100644 --- a/docs/api.md +++ b/docs/api.md @@ -124,3 +124,12 @@ getByText( Queries for test instance `stdout` results with the given text (and it also accepts a TextMatch). These options are all standard for text matching. To learn more, see our [Queries page](./queries.md). + +## `fireEvent` + +```javascript +fireEvent(instance: TestInstace, event: Event) +``` + +> While `fireEvent` isn't usually returned on `render` in, say, `React Testing Library`, we're able to do +> so because of our differences in implementation with upstream. See our [Differences](./differences.md) doc for more. diff --git a/docs/differences.md b/docs/differences.md index e582d8a..49e1bc3 100644 --- a/docs/differences.md +++ b/docs/differences.md @@ -1,4 +1,4 @@ -# Differences Between `@testing-library/dom` and `cli-testing-library` +# Differences Between `cli-testing-library` & Testing Library While we clearly take inspiration from [`DOM Testing Library`](https://github.com/testing-library/dom-testing-library) and [`React Testing Library`](https://github.com/testing-library/react-testing-library), @@ -43,9 +43,9 @@ While we would be happy to reconsider, there are once again # Events -Another area where we diverge from the DOM is in our event system (as implemented via `fireEvent`). +Another area where we diverge from the DOM is in our event system (as implemented via `fireEvent` and `userEvent`). -Despite our APIs naming indicating an actual event system (complete with bubbling and more, like the DOM), +Despite our APIs' naming indicating an actual event system (complete with bubbling and more, like the DOM), the CLI has no such concept. This means that, while `fireEvent` in the `DOM Testing Library` has the ability to inherent from all @@ -53,12 +53,21 @@ baked-into-browser events, we must hard-code a list of "events" and actions a us We try our best to implement ones that make sense: -- `fireEvent.up()` for keyboard up -- `fireEvent.type(str)` to write code into stdin +- `fireEvent.write({value: str})` to write `str` into stdin - `fireEvent.sigkill()` to send a [sigkill](https://en.wikipedia.org/wiki/Signal_(IPC)#SIGKILL) to the process +- `fireEvent.sigint()` to send a [sigint](https://en.wikipedia.org/wiki/Signal_(IPC)#SIGINT) to the process -But there are avenues where this diverges from upstream. [We have an open list of questions about how we can -make our events align more with upstream](https://github.com/crutchcorn/cli-testing-library/issues/2) +There is a missing API for that might make sense in `keypress`. It's unclear what this behavior would do that `write` wouldn't +be able to. + +There's also the API of `userEvent` that allows us to implement a fairly similar `keyboard` event +[to upstream](https://testing-library.com/docs/ecosystem-user-event/#keyboardtext-options). However, there are a few differences +here as well: + +1) `userEvent` can be bound to the `render` output. This is due to limitations of not having a `screen` API. It's unclear how + this would work in practice, due to a lack of the `window` API. +2) `userEvent.keyboard` does not support modifier keys. It's only key-presses, no holding. This is because of API + differences that would require us to figure out a manual binding system for every single key using ANSI AFAIK. # Matchers diff --git a/docs/fire-event.md b/docs/fire-event.md new file mode 100644 index 0000000..061c790 --- /dev/null +++ b/docs/fire-event.md @@ -0,0 +1,31 @@ +# Firing Events + +> **Note** +> +> Most projects have a few use cases for `fireEvent`, but the majority of the time you should probably use [`userEvent`](./user-event). + +## `fireEvent` + +```typescript +fireEvent(instance: TestInstance, event: EventString, eventProperties?: Object) +``` + +Fire CLI events. + +```javascript +fireEvent( + getByText(instance, 'Username:'), + 'write', + {value: 'crutchcorn'} +) +``` + +## `fireEvent[eventName]` + +```typescript +fireEvent[eventName](instance: TestInstance, eventProperties?: Object) +``` + +Convenience methods for firing CLI events. Check out +[src/event-map.js](https://github.com/crutchcorn/cli-testing-library/blob/main/src/event-map.js) +for a full list as well as default `eventProperties`.