feat: update README.md

Author: PatricioPoncini

README.md

@@ -2,7 +2,7 @@
 
 This repository contains a small backend server built with **Bun**, **Hono**, **Redis**, and **TypeScript**, designed as a playground for exploring different testing strategies.
 
-The goal of this project is to provide clear, practical examples of **unit tests**, **integration tests**, and **end-to-end (E2E) tests** while experimenting with modern backend tools.
+The project demonstrates how to structure a backend with singleton services and how to write unit, integration, and end-to-end (E2E) tests using real-world tools.
 
 ## `🚀 Tech Stack`
 
@@ -18,7 +18,84 @@ This project is intended as a **testing playground**, where you can:
 - Write and run **unit tests** for isolated logic
 - Build **integration tests** that interact with Redis and other services
 - Run **end-to-end tests** that exercise the entire API
-- Experiment with backend techniques using Bun and Hono
+- Experiment with backend design patterns like singleton services
+- Learn modern testing patterns in a minimal, modular codebase
+
+## `🔹 Singleton services`
+
+Both RedisService and HttpServer are implemented as singletons:
+
+- Ensures only one instance of Redis or HTTP server exists
+- Makes it easier to test, since you can start/stop them globally
+- Avoids conflicts when running multiple tests or endpoints simultaneously
+
+## `🧪 How tests work in this project`
+
+### `Unit tests`
+
+- Test individual services or functions in isolation, without starting HTTP server or connecting to Redis.
+- Focused on logic correctness.
+  Example: Testing `RedisService.lpush` with a mocked Redis client.
+
+```ts
+test("should call lPush on the client", async () => {
+  const fakeClient = {
+    lPush: mock(async () => 1),
+  };
+
+  (RedisService as any).client = fakeClient;
+
+  await RedisService.lpush("messages", "hello");
+
+  expect(fakeClient.lPush).toHaveBeenCalled();
+  expect(fakeClient.lPush).toHaveBeenCalledWith("messages", "hello");
+});
+```
+
+### `Integration tests`
+
+- Test how services work together.
+- RedisService singleton is used as-is, no mocking.
+- Redis must be running (`docker compose up -d`).
+
+```ts
+test("POST /messages → stores a new message successfully", async () => {
+  const req = new Request("http://localhost/messages", {
+    method: "POST",
+    body: JSON.stringify({ text: "hi" }),
+  });
+
+  const res = await messageRoutes.request("/", req);
+  expect(res.status).toBe(200);
+});
+```
+
+### `End-to-End (E2E) tests`
+
+- Test the full flow, including HTTP routes and Redis.
+- Simulate real API usage: POST a message → GET messages.
+- Ensures everything works together.
+
+```ts
+test("Should save a valid message and then retrieve it", async () => {
+  const body = {
+    text: "hi",
+  };
+  const postResponse = await axios.post<PostMessageResponse>(
+    "http://localhost:3000/messages",
+    body,
+  );
+  expect(postResponse.status).toBe(200);
+  expect(postResponse.data.ok).toBeTruthy();
+
+  const getResponse = await axios.get<GetMessagesResponse>(
+    "http://localhost:3000/messages",
+  );
+  expect(getResponse.status).toBe(200);
+  expect(getResponse.data.count).toEqual(1);
+  expect(getResponse.data.messages.length).toEqual(1);
+});
+```
 
 ## `▶️ Running the server`
 
@@ -34,11 +111,13 @@ The server will automatically reload when files change.
 bun test
 ```
 
-Tests will be progressively added across all categories (unit, integration, and E2E).
+- **Unit tests**: Test logic in isolation
+- **Integration tests**: Test services and external dependencies (Redis)
+- **E2E tests**: Test full API behavior
 
 ---
 
 ### `📝 Notes`
 
-This project is intentionally minimal and modular to make testing patterns easy to understand and extend.
-More test cases, utilities, and scenarios will be added over time.
+- The project is intentionally minimal and modular to make testing patterns easy to understand.
+- The README aims to provide immediate understanding of unit vs integration vs E2E tests in a practical backend project.

src/services/redisService.ts

@@ -4,9 +4,9 @@ export class RedisService {
   private static client: ReturnType<typeof createClient> | null = null;
 
   static async start() {
-    const c = createClient({ url: "redis://localhost:6379" });
-    await c.connect();
-    this.client = c;
+    const rc = createClient({ url: "redis://localhost:6379" });
+    await rc.connect();
+    this.client = rc;
     console.log("\x1b[32m 💾 Redis connected successfully \x1b[0m");
   }
 

src/types/redisTypes.ts

@@ -1,8 +1,10 @@
 import { describe, test, expect } from "bun:test";
 
-describe("Example test case", () => {
-  test("Simple sum", async () => {
-    const sum = 2 + 2;
-    expect(sum).toBe(4);
+describe("Math utilities – basic operations", () => {
+  test("should correctly sum two positive integers", () => {
+    const a = 2;
+    const b = 2;
+    const result = a + b;
+    expect(result).toBe(4);
   });
 });

test/e2e/e2e.test.ts test/e2e/messagesApi.test.tstest/e2e/e2e.test.ts renamed to test/e2e/messagesApi.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterAll, beforeAll } from "bun:test";
+import { describe, test, expect, afterAll, beforeAll } from "bun:test";
 import { messageRoutes } from "../../src/routes/messages";
 import { RedisService } from "../../src/services/redisService.ts";
 import type { ErrorResponse, GetMessagesResponse } from "../utils/types.ts";
@@ -14,7 +14,7 @@ describe("Message Routes – Integration Tests", () => {
   });
 
   describe("Success cases", () => {
-    it("GET /messages → returns an empty list when no messages exist", async () => {
+    test("GET /messages → returns an empty list when no messages exist", async () => {
       const req = new Request("http://localhost/messages");
       const res = await messageRoutes.request("/", req);
 
@@ -23,7 +23,7 @@ describe("Message Routes – Integration Tests", () => {
       expect(data.count).toBe(0);
     });
 
-    it("POST /messages → stores a new message successfully", async () => {
+    test("POST /messages → stores a new message successfully", async () => {
       const req = new Request("http://localhost/messages", {
         method: "POST",
         body: JSON.stringify({ text: "hi" }),
@@ -33,7 +33,7 @@ describe("Message Routes – Integration Tests", () => {
       expect(res.status).toBe(200);
     });
 
-    it("GET /messages → returns the previously stored message", async () => {
+    test("GET /messages → returns the previously stored message", async () => {
       const req = new Request("http://localhost/messages");
       const res = await messageRoutes.request("/", req);
 
@@ -42,7 +42,7 @@ describe("Message Routes – Integration Tests", () => {
       expect(data.count).toBe(1);
     });
 
-    it("POST /messages → returns only the first 10 messages after inserting 15", async () => {
+    test("POST /messages → returns only the first 10 messages after inserting 15", async () => {
       for (let i = 0; i < 15; i++) {
         const req = new Request("http://localhost/messages", {
           method: "POST",
@@ -68,7 +68,7 @@ describe("Message Routes – Integration Tests", () => {
   });
 
   describe("Error cases", () => {
-    it("POST /messages → returns 400 when body is missing", async () => {
+    test("POST /messages → returns 400 when body is missing", async () => {
       const req = new Request("http://localhost/messages", {
         method: "POST",
       });
@@ -80,7 +80,7 @@ describe("Message Routes – Integration Tests", () => {
       expect(data.error).toEqual("Invalid body: expected { text: string }");
     });
 
-    it("POST /messages → returns 400 when text is not a string", async () => {
+    test("POST /messages → returns 400 when text is not a string", async () => {
       const req = new Request("http://localhost/messages", {
         method: "POST",
         body: JSON.stringify({ text: 10 }),

test/example.test.ts

@@ -1,12 +1,12 @@
-import { describe, it, expect, mock, afterEach } from "bun:test";
+import { describe, test, expect, mock, afterEach } from "bun:test";
 import { RedisService } from "../../src/services/redisService";
 
 describe("RedisService - Unit tests", () => {
   afterEach(() => {
     (RedisService as any).client = null;
   });
 
-  it("should call lPush on the client", async () => {
+  test("should call lPush on the client", async () => {
     const fakeClient = {
       lPush: mock(async () => 1),
     };
@@ -19,7 +19,7 @@ describe("RedisService - Unit tests", () => {
     expect(fakeClient.lPush).toHaveBeenCalledWith("messages", "hello");
   });
 
-  it("should call lRange on the client", async () => {
+  test("should call lRange on the client", async () => {
     const fakeClient = {
       lRange: mock(async () => ["hi"]),
     };
@@ -33,7 +33,7 @@ describe("RedisService - Unit tests", () => {
     expect(result).toEqual(["hi"]);
   });
 
-  it("should return 15 elementos from 0 to 14", async () => {
+  test("should return 15 items from 0 to 14", async () => {
     const fakeClient = {
       lRange: mock(async () =>
         Array.from({ length: 15 }, (_, i) => `msg-${i}`),