test-fns 1.7.0 → 1.7.2

package/dist/usePrep.d.ts

@@ -8,5 +8,5 @@
 export declare const usePrep: <T extends Record<string, any>>(setup: () => Promise<T>, options?: {
     mode: 'beforeAll' | 'beforeEach';
 }) => T;
-export declare const useBeforeAll: <T extends Record<string, any>>(setup: Parameters<typeof usePrep<T>>[0]) => ReturnType<typeof usePrep>;
-export declare const useBeforeEach: <T extends Record<string, any>>(setup: Parameters<typeof usePrep<T>>[0]) => ReturnType<typeof usePrep>;
+export declare const useBeforeAll: <T extends Record<string, any>>(setup: Parameters<typeof usePrep<T>>[0]) => ReturnType<typeof usePrep<T>>;
+export declare const useBeforeEach: <T extends Record<string, any>>(setup: Parameters<typeof usePrep<T>>[0]) => ReturnType<typeof usePrep<T>>;

package/dist/usePrep.js.map

@@ -1 +1 @@
-{"version":3,"file":"usePrep.js","sourceRoot":"","sources":["../src/usePrep.ts"],"names":[],"mappings":";;;AAAA,mDAAyD;AAEzD;;;;;;GAMG;AACI,MAAM,OAAO,GAAG,CACrB,KAAuB,EACvB,UAEI,EAAE,IAAI,EAAE,WAAW,EAAE,EACtB,EAAE;IACL,wEAAwE;IACxE,MAAM,MAAM,GAAe,EAAE,CAAC,CAAC,8BAA8B;IAC7D,IAAI,OAAsB,CAAC,CAAC,uCAAuC;IAEnE,qDAAqD;IACrD,MAAM,YAAY,GAAsB;QACtC,GAAG,CAAC,CAAC,EAAE,IAAI;YACT,IAAI,OAAO,KAAK,SAAS;gBACvB,MAAM,IAAI,wCAAuB,CAC/B,uDAAuD,CACxD,CAAC;YACJ,OAAQ,OAAe,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QACD,OAAO;YACL,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,wBAAwB,CAAC,CAAC,EAAE,IAAI;YAC9B,OAAO,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACvD,CAAC;QACD,KAAK;YACH,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACpD,CAAC;KACF,CAAC;IAEF,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IAExE,QAAQ,CAAC,KAAK,IAAI,EAAE;QAClB,OAAO,GAAG,MAAM,KAAK,EAAE,CAAC;QAExB,+EAA+E;QAC/E,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAE/B,iEAAiE;QACjE,OAAO,YAAY,CAAC,GAAG,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,mDAAmD;IACnD,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,YAAY,CAAM,CAAC;AAC9C,CAAC,CAAC;AA5CW,QAAA,OAAO,WA4ClB;AAEK,MAAM,YAAY,GAAG,CAC1B,KAAuC,EACX,EAAE,CAAC,IAAA,eAAO,EAAI,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AAF7D,QAAA,YAAY,gBAEiD;AACnE,MAAM,aAAa,GAAG,CAC3B,KAAuC,EACX,EAAE,CAAC,IAAA,eAAO,EAAI,KAAK,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;AAF9D,QAAA,aAAa,iBAEiD"}
+{"version":3,"file":"usePrep.js","sourceRoot":"","sources":["../src/usePrep.ts"],"names":[],"mappings":";;;AAAA,mDAAyD;AAEzD;;;;;;GAMG;AACI,MAAM,OAAO,GAAG,CACrB,KAAuB,EACvB,UAEI,EAAE,IAAI,EAAE,WAAW,EAAE,EACtB,EAAE;IACL,wEAAwE;IACxE,MAAM,MAAM,GAAe,EAAE,CAAC,CAAC,8BAA8B;IAC7D,IAAI,OAAsB,CAAC,CAAC,uCAAuC;IAEnE,qDAAqD;IACrD,MAAM,YAAY,GAAsB;QACtC,GAAG,CAAC,CAAC,EAAE,IAAI;YACT,IAAI,OAAO,KAAK,SAAS;gBACvB,MAAM,IAAI,wCAAuB,CAC/B,uDAAuD,CACxD,CAAC;YACJ,OAAQ,OAAe,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QACD,OAAO;YACL,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,wBAAwB,CAAC,CAAC,EAAE,IAAI;YAC9B,OAAO,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACvD,CAAC;QACD,KAAK;YACH,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACpD,CAAC;KACF,CAAC;IAEF,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IAExE,QAAQ,CAAC,KAAK,IAAI,EAAE;QAClB,OAAO,GAAG,MAAM,KAAK,EAAE,CAAC;QAExB,+EAA+E;QAC/E,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAE/B,iEAAiE;QACjE,OAAO,YAAY,CAAC,GAAG,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,mDAAmD;IACnD,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,YAAY,CAAM,CAAC;AAC9C,CAAC,CAAC;AA5CW,QAAA,OAAO,WA4ClB;AAEK,MAAM,YAAY,GAAG,CAC1B,KAAuC,EACR,EAAE,CAAC,IAAA,eAAO,EAAI,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AAFhE,QAAA,YAAY,gBAEoD;AACtE,MAAM,aAAa,GAAG,CAC3B,KAAuC,EACR,EAAE,CAAC,IAAA,eAAO,EAAI,KAAK,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;AAFjE,QAAA,aAAa,iBAEoD"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "test-fns",
   "author": "ehmpathy",
   "description": "write usecase driven tests systematically for simpler, safer, and more readable code",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "repository": "ehmpathy/test-fns",
   "homepage": "https://github.com/ehmpathy/test-fns",
   "keywords": [

package/readme.md

@@ -72,6 +72,10 @@ describe('your test', () => {
 
 prepare test scenarios within a .given/.when block asynchronously, without any `let`s or `beforeAll`s
 
+`usePrep` accepts a `mode` option to control when setup runs:
+- `mode: 'beforeAll'` - runs setup once for all tests (default)
+- `mode: 'beforeEach'` - runs setup fresh before each test
+
 ```ts
 given('an overdue invoice', () => {
   const invoice = usePrep(async () => {
@@ -85,3 +89,97 @@ given('an overdue invoice', () => {
   })
 })
 ```
+
+**useBeforeAll and useBeforeEach are convenience wrappers** around `usePrep`:
+- `useBeforeAll(setup)` is equivalent to `usePrep(setup, { mode: 'beforeAll' })`
+- `useBeforeEach(setup)` is equivalent to `usePrep(setup, { mode: 'beforeEach' })`
+
+Use the named functions for clarity about when setup runs.
+
+### useBeforeAll
+
+prepare test resources once for all tests in a suite, optimizing setup time for expensive operations
+
+```ts
+describe('spaceship refueling system', () => {
+  given('a spaceship that needs to refuel', () => {
+    const spaceship = useBeforeAll(async () => {
+      // This runs once before all tests in this suite
+      const ship = await prepareExampleSpaceship();
+      await ship.dock();
+      return ship;
+    });
+
+    when('no changes are made', () => {
+      then('it should be docked', async () => {
+        expect(spaceship.isDocked).toEqual(true);
+      });
+
+      then('it should need fuel', async () => {
+        expect(spaceship.fuelLevel).toBeLessThan(spaceship.fuelCapacity);
+      });
+    });
+
+    when('it connects to the fuel station', () => {
+      const result = useBeforeAll(async () => await spaceship.connectToFuelStation());
+
+      then('it should be connected', async () => {
+        expect(result.connected).toEqual(true);
+      });
+
+      then('it should calculate required fuel', async () => {
+        expect(result.fuelNeeded).toBeGreaterThan(0);
+      });
+    });
+  });
+});
+```
+
+### useBeforeEach
+
+prepare fresh test resources before each test, ensuring test isolation
+
+```ts
+describe('spaceship combat system', () => {
+  given('a spaceship in battle', () => {
+    // This runs before each test, ensuring a fresh spaceship
+    const spaceship = useBeforeEach(async () => {
+      const ship = await prepareExampleSpaceship();
+      await ship.resetShields();
+      return ship;
+    });
+
+    when('no changes are made', () => {
+      then('it should have full shields', async () => {
+        expect(spaceship.shields).toEqual(100);
+      });
+
+      then('it should be ready for combat', async () => {
+        expect(spaceship.status).toEqual('READY');
+      });
+    });
+
+    when('it takes damage', () => {
+      const result = useBeforeEach(async () => await spaceship.takeDamage(25));
+
+      then('it should reduce shield strength', async () => {
+        expect(spaceship.shields).toEqual(75);
+      });
+
+      then('it should return damage report', async () => {
+        expect(result.damageReceived).toEqual(25);
+      });
+    });
+  });
+});
+```
+
+**When to use each:**
+- `useBeforeAll`: Use when setup is expensive (database connections, API calls) and tests don't modify the resource
+- `useBeforeEach`: Use when tests modify the resource and need isolation between runs
+- `usePrep`: The base function that powers both - use when you want explicit control over the mode or need to dynamically choose between `beforeAll` and `beforeEach`
+
+**Key differences:**
+- All three functions (`usePrep`, `useBeforeAll`, `useBeforeEach`) create a proxy that defers setup until the test framework's lifecycle hooks run
+- `useBeforeAll` and `useBeforeEach` are just clearer, more readable shortcuts for `usePrep` with a specific mode
+- Choose based on readability: use `useBeforeAll`/`useBeforeEach` for explicit intent, or `usePrep` when mode needs to be configurable