Typed TestRequest for API integration and E2E tests

Now it'll be possible to provide named setup without the need to reference Supertest in the end project

Author: oskardudycz

src/docs/snippets/gettingStarted/webApi/apiBDD.e2e.spec.ts

@@ -10,6 +10,7 @@ import {
   ApiE2ESpecification,
   expectResponse,
   getApplication,
+  type TestRequest,
 } from '@event-driven-io/emmett-expressjs';
 import {
   EventStoreDBContainer,
@@ -52,24 +53,20 @@ void describe('ShoppingCart E2E', () => {
   });
 
   void describe('When opened with product item', () => {
-    void it('should confirm', () => {
-      return given((request) =>
-        request
-          .post(`/clients/${clientId}/shopping-carts/current/product-items`)
-          .send(productItem),
-      )
+    const openedShoppingCartWithProduct: TestRequest = (request) =>
+      request
+        .post(`/clients/${clientId}/shopping-carts/current/product-items`)
+        .send(productItem);
+
+    void it('should confirm', () =>
+      given(openedShoppingCartWithProduct)
         .when((request) =>
           request.post(`/clients/${clientId}/shopping-carts/current/confirm`),
         )
-        .then([expectResponse(204)]);
-    });
+        .then([expectResponse(204)]));
 
-    void it('should return details', () => {
-      return given((request) =>
-        request
-          .post(`/clients/${clientId}/shopping-carts/current/product-items`)
-          .send(productItem),
-      )
+    void it('should return details', () =>
+      given(openedShoppingCartWithProduct)
         .when((request) =>
           request.get(`/clients/${clientId}/shopping-carts/current`).send(),
         )
@@ -87,8 +84,7 @@ void describe('ShoppingCart E2E', () => {
               status: ShoppingCartStatus.Opened,
             },
           }),
-        ]);
-    });
+        ]));
   });
 
   const now = new Date();

src/docs/snippets/gettingStarted/webApi/apiBDDE2ETest.ts

@@ -2,6 +2,7 @@ import { type EventStore } from '@event-driven-io/emmett';
 import {
   ApiE2ESpecification,
   getApplication,
+  type TestRequest,
 } from '@event-driven-io/emmett-expressjs';
 import { randomUUID } from 'node:crypto';
 import { describe, it } from 'node:test';
@@ -43,12 +44,13 @@ import { expectResponse } from '@event-driven-io/emmett-expressjs';
 import type { StartedEventStoreDBContainer } from '@event-driven-io/emmett-testcontainers';
 
 void describe('When opened with product item', () => {
+  const openedShoppingCartWithProduct: TestRequest = (request) =>
+    request
+      .post(`/clients/${clientId}/shopping-carts/current/product-items`)
+      .send(productItem);
+
   void it('should confirm', () => {
-    return given((request) =>
-      request
-        .post(`/clients/${clientId}/shopping-carts/current/product-items`)
-        .send(productItem),
-    )
+    return given(openedShoppingCartWithProduct)
       .when((request) =>
         request.post(`/clients/${clientId}/shopping-carts/current/confirm`),
       )

src/packages/emmett-expressjs/src/testing/apiE2ESpecification.ts

@@ -1,6 +1,4 @@
-import type { Test } from 'supertest';
 import supertest, { type Response } from 'supertest';
-import type TestAgent from 'supertest/lib/agent';
 
 import type {
   DefaultStreamVersionType,
@@ -9,15 +7,14 @@ import type {
 import assert from 'assert';
 import type { Application } from 'express';
 import { WrapEventStore } from './utils';
+import type { TestRequest } from './apiSpecification';
 
 export type E2EResponseAssert = (response: Response) => boolean | void;
 
 export type ApiE2ESpecificationAssert = [E2EResponseAssert];
 
-export type ApiE2ESpecification = (
-  ...givenRequests: ((request: TestAgent<supertest.Test>) => Test)[]
-) => {
-  when: (setupRequest: (request: TestAgent<supertest.Test>) => Test) => {
+export type ApiE2ESpecification = (...givenRequests: TestRequest[]) => {
+  when: (setupRequest: TestRequest) => {
     then: (verify: ApiE2ESpecificationAssert) => Promise<void>;
   };
 };
@@ -28,16 +25,12 @@ export const ApiE2ESpecification = {
     getApplication: (eventStore: EventStore<StreamVersion>) => Application,
   ): ApiE2ESpecification => {
     {
-      return (
-        ...givenRequests: ((request: TestAgent<supertest.Test>) => Test)[]
-      ) => {
+      return (...givenRequests: TestRequest[]) => {
         const eventStore = WrapEventStore(getEventStore());
         const application = getApplication(eventStore);
 
         return {
-          when: (
-            setupRequest: (request: TestAgent<supertest.Test>) => Test,
-          ) => {
+          when: (setupRequest: TestRequest) => {
             const handle = async () => {
               for (const requestFn of givenRequests) {
                 await requestFn(supertest(application));

src/packages/emmett-expressjs/src/testing/apiSpecification.ts

@@ -16,6 +16,8 @@ import { WrapEventStore, type TestEventStream } from './utils';
 /////////// Setup
 ////////////////////////////////
 
+export type TestRequest = (request: TestAgent<supertest.Test>) => Test;
+
 export const existingStream = <EventType extends Event = Event>(
   streamId: string,
   events: EventType[],
@@ -76,7 +78,7 @@ export const expectError = (
 export type ApiSpecification<EventType extends Event = Event> = (
   ...givenStreams: TestEventStream<EventType>[]
 ) => {
-  when: (setupRequest: (request: TestAgent<supertest.Test>) => Test) => {
+  when: (setupRequest: TestRequest) => {
     then: (verify: ApiSpecificationAssert<EventType>) => Promise<void>;
   };
 };
@@ -95,9 +97,7 @@ export const ApiSpecification = {
         const application = getApplication(eventStore);
 
         return {
-          when: (
-            setupRequest: (request: TestAgent<supertest.Test>) => Test,
-          ) => {
+          when: (setupRequest: TestRequest) => {
             const handle = async () => {
               for (const [streamName, events] of givenStreams) {
                 await eventStore.setup(streamName, events);