feat: add api tests module

Author: kuroidoruido

demo-app/package.json

@@ -1,5 +1,6 @@
 {
   "name": "demo-app",
+  "version": "1.0.0",
   "type": "module",
   "scripts": {
     "dev": "tsx watch src/index.tsx"

demo-app/src/api/app/health.ts

@@ -0,0 +1,30 @@
+import { describeRoute } from "hono-openapi";
+import { PRODUCTS, ProductSchema } from "../../data/products.js";
+import { resolver } from "hono-openapi/zod";
+import { z } from "zod";
+
+export const HealthSchema = z.object({
+    status: z.union([z.literal("UP"), z.literal("DOWN")]),
+});
+
+export type Health = z.infer<typeof HealthSchema>;
+
+export function getHealthDoc() {
+    return describeRoute({
+        description: "Get api health",
+        responses: {
+            200: {
+                description: "Successful response",
+                content: {
+                    "application/json": {
+                        schema: resolver(z.array(HealthSchema)),
+                    },
+                },
+            },
+        },
+    });
+}
+
+export function getHealth(): Health {
+    return { status: "UP" };
+}

demo-app/src/api/app/info.ts

@@ -0,0 +1,31 @@
+import { describeRoute } from "hono-openapi";
+import { resolver } from "hono-openapi/zod";
+import { z } from "zod";
+import packageJson from "../../../package.json";
+
+export const InfoSchema = z.object({
+    name: z.string(),
+    version: z.string(),
+});
+
+export type Info = z.infer<typeof InfoSchema>;
+
+export function getInfoDoc() {
+    return describeRoute({
+        description: "Get api info",
+        responses: {
+            200: {
+                description: "Successful response",
+                content: {
+                    "application/json": {
+                        schema: resolver(z.array(InfoSchema)),
+                    },
+                },
+            },
+        },
+    });
+}
+
+export function getInfo(): Info {
+    return { name: packageJson.name, version: packageJson.version };
+}

demo-app/src/api/app/mappings.ts

@@ -0,0 +1,36 @@
+import { describeRoute } from "hono-openapi";
+import { resolver } from "hono-openapi/zod";
+import { z } from "zod";
+import packageJson from "../../../package.json";
+import type { Hono } from "hono";
+
+export const MappingsSchema = z.object({
+    mappings: z.array(z.object({
+        method: z.string(),
+        path: z.string(),
+    })),
+});
+
+export type Mappings = z.infer<typeof MappingsSchema>;
+
+export function getMappingsDoc() {
+    return describeRoute({
+        description: "Get api mappings",
+        responses: {
+            200: {
+                description: "Successful response",
+                content: {
+                    "application/json": {
+                        schema: resolver(z.array(MappingsSchema)),
+                    },
+                },
+            },
+        },
+    });
+}
+
+export function getMappings(app: Hono): Mappings {
+    return {
+        mappings: app.routes.map((r) => ({ method: r.method, path: r.path })),
+    };
+}

demo-app/src/index.tsx

@@ -19,6 +19,9 @@ import { GUESTBOOK } from './data/guestbook.js';
 import { Login } from './pages/login.js';
 import { ProvideHonoContext } from './utils/context.js';
 import { AdminGuestbook } from './pages/admin-guestbook.js';
+import { getHealth, getHealthDoc } from './api/app/health.js';
+import { getInfo, getInfoDoc } from './api/app/info.js';
+import { getMappings, getMappingsDoc } from './api/app/mappings.js';
 
 const app = new Hono();
 
@@ -49,10 +52,13 @@ app
   .get('/pastry', (c) => c.html(withContexts(Pastry, c)))
   .get('/terms-and-conditions', (c) => c.html(withContexts(TermsAndConditions, c)))
   // api
+  .get('/api/app/health', getHealthDoc(), (c) => c.json(getHealth()))
+  .get('/api/app/info', getInfoDoc(), (c) => c.json(getInfo()))
+  .get('/api/app/mappings', getMappingsDoc(), (c) => c.json(getMappings(app)))
   .get('/api/v1/discoveries', getDiscoveriesDoc(), (c) => c.json(getDiscoveries()))
   // swagger
   .get(
-    '/doc',
+    '/api/doc',
     openAPISpecs(app, {
       documentation: {
         info: {
@@ -64,9 +70,9 @@ app
       },
     })
   )
-  .get('/swagger', swaggerUI({ url: '/doc' }))
-  .get('/swagger-ui', swaggerUI({ url: '/doc' }))
-  .get('/swagger-ui/index.html', swaggerUI({ url: '/doc' }));
+  .get('/api/swagger', swaggerUI({ url: '/api/doc' }))
+  .get('/api/swagger-ui', swaggerUI({ url: '/api/doc' }))
+  .get('/api/swagger-ui/index.html', swaggerUI({ url: '/api/doc' }));
 
 const port = 3000;
 console.log(`Server is running on http://localhost:${port}`);

demo-app/tsconfig.json

@@ -5,10 +5,9 @@
     "strict": true,
     "verbatimModuleSyntax": true,
     "skipLibCheck": true,
-    "types": [
-      "node"
-    ],
+    "types": ["node"],
     "jsx": "react-jsx",
     "jsxImportSource": "hono/jsx",
+    "resolveJsonModule": true
   }
-}
+}

docs/markdown/08-api-tests/10-make-api-call.md

@@ -0,0 +1,110 @@
+<!-- .slide: class="transition" -->
+
+# Make API call
+
+##==##
+
+<!-- .slide: class="with-code" -->
+
+# Access the page...
+
+```TypeScript
+test('ui test', ({ page }) => {
+    await page.goto('/');
+});
+```
+
+<!-- .element: class="big-code" -->
+
+Notes:
+
+- as we see before
+
+##==##
+
+<!-- .slide: class="with-code" -->
+
+# Access the API!
+
+```TypeScript
+test('ui test', ({ page }) => {
+    await page.goto('/');
+});
+
+test('api test', ({ request }) => {
+    await request.get('/api/health');
+});
+```
+
+<!-- .element: class="big-code" -->
+
+Notes:
+
+- as simple as before!
+- Playwright offer the request fixture built-in
+- it gives method to make any api calls
+
+##==##
+
+<!-- .slide: class="with-code" -->
+
+# Exemple 1: simulate submitting a login form
+
+```TypeScript
+const res = await request.post('/api/login', {
+    form: { email: '[email protected]', password: 'SuperSecure1' }
+});
+```
+
+<!-- .element: class="big-code" -->
+
+Notes:
+
+- to speed up auth, we can use api call to simulate login
+- pay attention, it's not how the user will authenticate, so keep some test using the UI!
+
+##==##
+
+<!-- .slide: class="with-code" -->
+
+# Exemple 1: simulate submitting a login form (FormData version)
+
+```TypeScript
+const form = new FormData();
+form.set('email', '[email protected]')
+form.set('password', 'SuperSecure1')
+const res = await request.post('/api/login', { form });
+```
+
+<!-- .element: class="big-code" -->
+
+##==##
+
+<!-- .slide: class="with-code" -->
+
+# Exemple 2: make an authenticate POST call
+
+```TypeScript
+const res = await request.post('/api/v1/secret-user-data', {
+    headers: { 'Authorization': 'Bearer A.Pretty-Legit-Jwt.Token' }
+});
+```
+
+<!-- .element: class="big-code" -->
+
+##==##
+
+<!-- .slide: class="with-code" -->
+
+# Exemple 3: cleanup data after running a UI test
+
+```TypeScript
+const res = await request.delete(`/api/v1/messages/${messageIdCreatedDuringTheTest}`);
+```
+
+<!-- .element: class="big-code" -->
+
+Notes:
+
+- some times we want to cleanup data we created/updated during the test
+- using API call it can be easier to make this cleanup!

docs/markdown/08-api-tests/20-response-validation.md

@@ -0,0 +1,62 @@
+<!-- .slide: class="transition" -->
+
+# Response validation
+
+##==##
+
+<!-- .slide: class="with-code" -->
+
+# Checking response status
+
+```TypeScript
+const res = await request.get('/api/health');
+expect(res.status()).toBe(200);
+```
+
+<!-- .element: class="big-code" -->
+
+Notes:
+
+- the result of the request methods call will give access to the full response
+- we can get the status for example and checking the value with low level assertions (the ones that does not make any retry or DOM actions)
+
+##==##
+
+<!-- .slide: class="with-code" -->
+
+# Checking response headers
+
+```TypeScript
+const res = await request.post('/api/login', {
+    form: { email: '[email protected]', password: 'SuperSecure1' }
+});
+expect(body.headers()).toHaveProperty('Content-Type');
+expect(body.headers()['Content-Type']).toBe('application/json');
+```
+
+<!-- .element: class="big-code" -->
+
+Notes:
+
+- nothing special, but you can access headers too
+
+##==##
+
+<!-- .slide: class="with-code" -->
+
+# Checking response body
+
+```TypeScript
+const res = await request.post('/api/login', {
+    form: { email: '[email protected]', password: 'SuperSecure1' }
+});
+const body = await res.json();
+expect(body.token).not.toHaveLenght(0);
+```
+
+<!-- .element: class="big-code" -->
+
+Notes:
+
+- to access the body (here as json, but as text, buffer, stream, blob, etc.) we need to await it
+- then you can manipulate the body as you want like you can make with a `fetch()` response

docs/markdown/08-api-tests/30-mix-between-api-tests-and-e2e-tests.md

@@ -0,0 +1,17 @@
+<!-- .slide: class="transition" -->
+
+# Mix between API tests and E2E Tests
+
+##==##
+
+<!-- .slide: class="quote-slide" -->
+
+## When use API tests ? When E2E Tests ?
+
+Notes:
+
+- it depends on your test's strategy
+- most of the time: make a mix of both,
+  - some things are easier/faster to test on API level
+  - some things can only be tested with E2E to be realistic
+- recommendation: create a separate project for API testing (what will not make on the lab), it will be easier to keep tidy

docs/markdown/08-api-tests/99-lab-writing-an-api-test-suite.md

@@ -6,12 +6,10 @@
 
 <br>
 
-1. TODO
-2. TODO
-3. TODO
-
-<br>
-
-- TODO
+1. Create a new file `tests/api.spec.ts` ;
+2. Create a test that check `GET /api/app/health` ;
+3. Create a test that check `GET /api/app/info` ;
+4. Create a test that check `GET /api/app/mappings` ;
+5. Create a test that check `GET /api/v1/discoveries` ;
 
 ### npm run 07-api-tests