[RFC] Upstream Alignment Reference Questions

As should be obvious, we're trying to match the upstream example of Testing Library ecosystem as closely as possible. This even extends so far as our source code and release/dev tooling.

---

However, there are some existing APIs in related packages that I'm admittedly not sure how they would fit/migrate into the CLI environment

General Questions

Library Merging

Currently, this library does the job that the broader Testing Library ecosystem would usually split into a few different packages:

• jest-dom for Jest matchers
• dom-testing-library for queries, normalization, etc
• react-testing-library for render logic and additions
• user-event for keyboard events

On top of this, we also have our docs stored in this folder, whereareas upstream has a dedicated repo and website.

Theoretically, we could break these into separate libraries but there's a few problems with this:

1. Without a specific org, it'd be difficult to see all the relevant repos in my personal namespace on GitHub. While I'm not against making an org, ideally we'd be able to merge upstream into the Testing Library org instead.
2. While dom-testing-library and dependents have the benefit of relying on W3C web standards, we do not. The only standards present for the CLI are, well, the CLI itself. There is many instances where, unfortunately, logic is interconnected by requirement. It makes little/no sense to split them when their logic is so interconnected

Instance

While we have an implementation present, it's unclear what a TestInstance properly should be, or if that should even be it's name.

We've done our best; for example, to align with container of upstream, we have the return result of spawn set to container in CLI Testing Library.

However, because there is no distinction between stdout and stderr outputs (oftentimes a CLI app will output multiple items one-by-one to be visually similar to one-another), there's no way to have the same kind of parent/child relationship that the DOM has. This has many unintended consequences that we'll see shortly.

---

Further, what should we be calling TestInstance? They're meant to be a replacement to HTMLElement and returned by RenderResult.

Here are some alternatives I can think of:

• Process (not a huge fan of this one)
• CliInstance
• CommandLine
• Console

Window

Something that I think comes in handy, from a library perspective, is a global that keeps track of all running processes, like window in the DOM.

While it wasn't needed in v1 (quite yet), it will make some refactor work possible. As such, I want to include it in v2.

Two questions related to that.

1: What should we call it?

• Machine (I like this one TBH)
• OS
• Kernel

2: What should the shape look like?

window has many helper methods, and such. We could do something like:

{
    // `kill` all processes
    shutdown(): void;
    // `kill` PID from `prosseses`
    kill(pid: number): Promise<void>;
    processes: TestInstance[];
}

dom-testing-library Reference Questions

Queries

While we have singular queries (such as findByText and findByError), we do not currently have multiple matcher queries.

• queryAllBy
• findAllBy
• getAllBy

This is because, as mentioned before, there is no reference for what these should return. There are no distinctions between stdout or stderr lines, and there's no major parent/child relationship I can think of that would make sense.

jest-dom Reference Questions

While we have some matchers similar to jest-dom (EG: toBeInTheConsole), would it also make sense to add something like:

• toHaveANSIEscapeModifier - Test to see if a related ANSI Escape Code applied to the line

Start with the existing v1 implementation around spawn, TestInstance, and RenderResult, then compare the linked upstream Testing Library packages and the docs folder. Resolve the proposed naming, process-global shape, multi-match queries, and ANSI matcher scope; done means the API decisions and migration boundaries are agreed and documented.