From f1678074713711db6e40d27545ee217688ce2eeb Mon Sep 17 00:00:00 2001 From: Jonathan Tsai Date: Wed, 25 Feb 2026 08:27:25 +0000 Subject: [PATCH] docs: add testing strategy for pre-publish verification Co-Authored-By: Claude Opus 4.6 --- TESTING.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 TESTING.md diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 0000000..c2ee50f --- /dev/null +++ b/TESTING.md @@ -0,0 +1,72 @@ +# Testing Strategy + +## Philosophy + +Before publishing a new version to npm, we must verify the **full pipeline** end-to-end: + +**Source code** -> **TypeScript build** -> **npm pack** -> **npm install (tarball)** -> **Consumer site build** -> **Live site verification** + +This ensures the package is correctly built, packaged, and consumable by real downstream projects. Unit tests alone cannot catch packaging issues (missing files, broken exports, module format mismatches, etc.). + +## Pre-Publish Checklist + +### 1. Build the package + +```bash +cd packages/core +rm -rf dist tsconfig.tsbuildinfo +npx tsc +``` + +Verify: no errors, `dist/` directory populated. + +### 2. Pack the tarball + +```bash +npm pack --dry-run # inspect contents first +npm pack # create the .tgz +``` + +Verify: +- No warnings (especially about `bin` entries being removed) +- All expected files present: `dist/`, `templates/`, `bin/`, `README.md`, `LICENSE` +- No unexpected files (no `src/`, no internal planning docs) + +### 3. Install into consumer projects + +```bash +cd /path/to/consumer-project +rm -rf node_modules/@hacktoolkit .next +npm install /path/to/hacktoolkit-nextjs-htk-X.Y.Z.tgz +make build +``` + +Repeat for each consumer project. + +Verify: build completes successfully. + +### 4. Verify on dev/staging site + +If you have a dev or staging environment that serves from the `docs/` directory (Next.js static export), `make build` immediately updates the live site. Verify with `curl` or a browser. + +### 5. Break-fix test + +To confirm the package is actually being used (not cached/stale): + +1. **Break**: Modify a function in the package source (e.g., prefix `buildFullAddress` output with `BROKEN-PKG-TEST`) +2. **Build + Pack**: `npx tsc && npm pack` +3. **Install**: `npm install /path/to/tarball.tgz` +4. **Rebuild consumer**: `rm -rf .next && make build` +5. **Verify broken**: Check the built output or dev site and confirm the broken output appears +6. **Fix**: Revert the source change +7. **Repeat steps 2-4** +8. **Verify fixed**: Confirm the broken output is gone + +**Important**: Always `rm -rf .next` before rebuilding - Next.js aggressively caches and may serve stale output. + +## Known Gotchas + +- **`tsconfig.tsbuildinfo` cache**: If `incremental: true` is set (inherited from root tsconfig), tsc may skip emitting files if it thinks nothing changed. Always delete `tsconfig.tsbuildinfo` before a clean build. +- **Next.js `.next` cache**: Must `rm -rf .next` when testing package changes, otherwise the consumer build may use cached modules. +- **`"type": "module"` incompatibility**: The compiled TypeScript output uses extensionless imports (`export * from './address'`). Node.js ESM requires explicit extensions, so `"type": "module"` must NOT be set. Bundlers (Next.js/webpack) handle extensionless imports fine. +- **npm tarball vs symlink**: When installing from a tarball (`npm install ./file.tgz`), npm copies files. When using `file:` protocol in package.json, npm creates a symlink. The tarball test is closer to what real consumers experience from npm.