Merge branch 'alpha-docs' into alpha

crutchcorn · crutchcorn · commit ade26c3519b2 · 2021-12-13T21:42:53.000-08:00
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -20,8 +20,17 @@
         "doc",
         "maintenance"
       ]
+    },
+    {
+      "login": "SerkanSipahi",
+      "name": "Bitcollage",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1880749?v=4",
+      "profile": "https://www.linkedin.com/in/serkan-sipahi-59b20081/",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "repoHost": "https://github.com",
   "commitConvention": "none"
-}
+}
diff --git a/README.md b/README.md
@@ -21,12 +21,11 @@ practices.</p>
 [![version](https://img.shields.io/npm/v/cli-testing-library?style=flat-square)](https://www.npmjs.com/package/cli-testing-library)
 [![downloads](https://img.shields.io/npm/dw/cli-testing-library?style=flat-square)](https://www.npmjs.com/package/cli-testing-library)
 [![MIT License](https://img.shields.io/npm/l/cli-testing-library?style=flat-square)](./LICENSE)
-[![All Contributors](https://img.shields.io/badge/all_contributors-7-blue.svg?style=flat-square)](#contributors)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](makeapullrequest.com)
 [![Code of Conduct](https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square)](./CODE_OF_CONDUCT.md)
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 [![Watch on GitHub](https://img.shields.io/github/watchers/crutchcorn/cli-testing-library.svg?style=social)](https://github.com/crutchcorn/cli-testing-library/watchers)
@@ -109,6 +108,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <table>
   <tr>
     <td align="center"><a href="https://crutchcorn.dev/"><img src="https://avatars.githubusercontent.com/u/9100169?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Corbin Crutchley</b></sub></a><br /><a href="https://github.com/crutchcorn/cli-testing-library/commits?author=crutchcorn" title="Code">💻</a> <a href="https://github.com/crutchcorn/cli-testing-library/commits?author=crutchcorn" title="Documentation">📖</a> <a href="#maintenance-crutchcorn" title="Maintenance">🚧</a></td>
+    <td align="center"><a href="https://www.linkedin.com/in/serkan-sipahi-59b20081/"><img src="https://avatars.githubusercontent.com/u/1880749?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Bitcollage</b></sub></a><br /><a href="https://github.com/crutchcorn/cli-testing-library/commits?author=SerkanSipahi" title="Documentation">📖</a></td>
   </tr>
 </table>
 
diff --git a/docs/api.md b/docs/api.md
@@ -216,3 +216,27 @@ interface TestInstance {
 This method acts as the terminal `clear` command might on most systems. It
 allows you to clear out the buffers for `stdoutArr` and `stderrArr` - even in
 the middle of processing - in order to do more narrowed queries.
+
+# `cleanup`
+
+`SIGKILL`s processes that were spawned with render and have not halted by the end of the test.
+
+> Please note that this is done automatically if the testing framework you're using supports the `afterEach` global and it is injected to your testing environment (like mocha, Jest, and Jasmine). If not, you will need to do manual cleanups after each test.
+
+For example, if you're using the [ava](https://github.com/avajs/ava) testing framework, then you would need to use the `test.afterEach` hook like so:
+
+```javascript
+import {cleanup, render} from 'cli-testing-library'
+import test from 'ava'
+
+test.afterEach(cleanup)
+
+test('renders into document', () => {
+  render('long-running-command')
+  // ...
+})
+
+// ... more tests ...
+```
+
+Failing to call cleanup when you've called render could result in Jest failing to close due to unclosed handles and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests).
diff --git a/docs/configure.md b/docs/configure.md
@@ -1,5 +1,18 @@
 # Configuration Options
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Introduction](#introduction)
+- [Options](#options)
+  - [`showOriginalStackTrace`](#showoriginalstacktrace)
+  - [`throwSuggestions` (experimental)](#throwsuggestions-experimental)
+  - [`getInstanceError`](#getinstanceerror)
+  - [`asyncUtilTimeout`](#asyncutiltimeout)
+  - [`renderAwaitTime`](#renderawaittime)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Introduction
 
 The library can be configured via the `configure` function, which accepts:
diff --git a/docs/debug.md b/docs/debug.md
@@ -1,5 +1,13 @@
 # Debug
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Automatic Logging](#automatic-logging)
+- [`prettyCLI`](#prettycli)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Automatic Logging
 
 When you use any `get` calls in your test cases, the current state of the
diff --git a/docs/differences.md b/docs/differences.md
@@ -13,8 +13,8 @@ distinctions between the project's APIs.
 - [Instances](#instances)
 - [Queries](#queries)
 - [Events](#events)
-  - [FireEvent](#fireevent)
-  - [UserEvent](#userevent)
+    - [FireEvent](#fireevent)
+    - [UserEvent](#userevent)
 - [Matchers](#matchers)
 - [Similarities](#similarities)
 
diff --git a/docs/fire-event.md b/docs/fire-event.md
@@ -1,9 +1,6 @@
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-**Table of Contents** _generated with
-[DocToc](https://github.com/thlorenz/doctoc)_
-
 - [Firing Events](#firing-events)
   - [`fireEvent`](#fireevent)
   - [`fireEvent[eventName]`](#fireeventeventname)
diff --git a/docs/introduction.md b/docs/introduction.md
@@ -10,6 +10,8 @@ npm install --save-dev cli-testing-library
 
 - [`cli-testing-library` on GitHub](https://github.com/crutchcorn/cli-testing-library)
 
+## Table of Contents
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
@@ -46,3 +48,14 @@ will work when a real user uses it.
 
 1. A test runner or framework
 2. Specific to a testing framework (though we recommend Jest as our preference, the library works with any framework.)
+
+# Further Reading
+
+- [API reference for `render` and friends](./api.md)
+- [Jest matchers](./matchers.md)
+- [Mock user input](./user-event.md)
+- [Manually fire input events](./fire-event.md)
+- [Output matching queries](./queries.md)
+- [Debugging "CLI Testing Library" tests](./debug.md)
+- [Configure library options](./configure.md)
+- [Differences between us and other "Testing Library" projects](./differences.md)
diff --git a/docs/user-event.md b/docs/user-event.md
@@ -4,9 +4,6 @@ interactions than the [`fireEvent`](./fire-event) method.
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-**Table of Contents** _generated with
-[DocToc](https://github.com/thlorenz/doctoc)_
-
 - [Import](#import)
 - [API](#api)
   - [`keyboard(instance, text, [options])`](#keyboardinstance-text-options)
