From 786149b0d74cf2fb877c8099e8ab5a8c1a7808e5 Mon Sep 17 00:00:00 2001 From: Marc Cataford Date: Sat, 8 Apr 2023 11:18:30 -0400 Subject: [PATCH] docs: retcon some documentation on dependencies, snapshots (#16) --- DESIGN_DECISIONS.md | 28 ++++++++++++++++++++++++++++ README.md | 5 +++++ 2 files changed, 33 insertions(+) create mode 100644 DESIGN_DECISIONS.md diff --git a/DESIGN_DECISIONS.md b/DESIGN_DECISIONS.md new file mode 100644 index 0000000..ce89d65 --- /dev/null +++ b/DESIGN_DECISIONS.md @@ -0,0 +1,28 @@ +# Design decisions + +`womm` mostly shadows the API of other test runners out there with a few quirks. This document records choices made +along the way and the reasoning behind them. + +## No production dependencies + +I believe that the NodeJS ecosystem is too trigger-happy with `npm install` and `yarn add`. Even basic applications +quickly end up requiring tens of packages to be shipped to users. A lot of those packages being maintained (or not) by +the community, this means that ensuring that the downstream dependency of a project can quickly become a major concern. + +The best way to ensure that things are becoming stale is to depend on less, and depending on nothing than the standard +library is best. + +_Some exceptions apply here. Development tooling is easier to handle, but should still be heavily vetted. For this +reason, `womm` has a few dev-facing dependencies, but those are carefully-chosen to make sure that the cost of having +them doesn't outweigh what they bring to the table._ + +## No snapshot matchers + +Snapshot testing is rarely used well. In a lot of cases, it's a crutch used to avoid writing more precise assertions +about software behaviour. This is especially true in browser-facing code where component snapshots clutter codebases and +provide very little confidence that code is healthy -- instead, it measures whether it changed or evolved, and expects +whoever _reads_ the test to validate snapshot contents manually. + +Snapshot matchers are not included out-of-the-box in `womm` to promote better practices around test quality and to +remove a foot-gun from the tooling. + diff --git a/README.md b/README.md index 643cfab..71c8112 100644 --- a/README.md +++ b/README.md @@ -14,3 +14,8 @@ constraints: `rome`, but keeping it to a minimum); - It must be compatible with the general API exposed by Jest and the like, for familiarity; - It must use itself for testing. + +### Hot takes baked in + +`womm` is an opinionated implementation of Typescript/Javascript testing libraries we've all come to get used to. You +can peek at the opinions baked into this [here](./DESIGN_DECISIONS.md).