balda-js 0.0.1 → 0.0.3

package/docs/docs/testing/examples.md

@@ -1,384 +0,0 @@
-# Testing Examples
-
-This guide provides practical examples of testing with Balda.js MockServer, covering common scenarios and patterns.
-
-## Basic API Testing
-
-### Simple GET Request
-```typescript
-import { describe, it, expect } from "vitest";
-import { mockServer } from "test/server/instance";
-
-describe("Basic API Tests", () => {
-  it("GET /users returns user list", async () => {
-    const res = await mockServer.get("/users");
-
-    expect(res.statusCode()).toBe(200);
-    expect(Array.isArray(res.body())).toBe(true);
-    expect(res.body().length).toBeGreaterThan(0);
-  });
-});
-```
-
-### GET with Query Parameters
-```typescript
-it("GET /users with pagination", async () => {
-  const res = await mockServer.get("/users", {
-    query: { page: "1", limit: "5" }
-  });
-
-  expect(res.statusCode()).toBe(200);
-  expect(res.body().length).toBeLessThanOrEqual(5);
-});
-```
-
-### GET with Headers
-```typescript
-it("GET /protected with authorization", async () => {
-  const res = await mockServer.get("/protected", {
-    headers: { "Authorization": "Bearer token123" }
-  });
-
-  expect(res.statusCode()).toBe(200);
-});
-```
-
-## POST Request Testing
-
-### JSON Body
-```typescript
-it("POST /users creates new user", async () => {
-  const newUser = {
-    name: "John Doe",
-    email: "john@example.com",
-    age: 30
-  };
-
-  const res = await mockServer.post("/users", { body: newUser });
-
-  expect(res.statusCode()).toBe(201);
-  expect(res.assertBodyDeepEqual(newUser));
-});
-```
-
-### Form Data (URL Encoded)
-```typescript
-it("POST /users with form data", async () => {
-  const res = await mockServer.post("/users", {
-    urlencoded: {
-      name: "Jane Doe",
-      email: "jane@example.com",
-      age: "25"
-    }
-  });
-
-  expect(res.statusCode()).toBe(201);
-  expect(res.assertBodySubset({ name: "Jane Doe" }));
-});
-```
-
-### File Upload
-```typescript
-it("POST /upload handles file upload", async () => {
-  const formData = new FormData();
-  const fileContent = new Uint8Array([1, 2, 3, 4, 5]);
-  formData.append("file", new Blob([fileContent]), "test.txt");
-
-  const res = await mockServer.post("/upload", { formData });
-
-  expect(res.statusCode()).toBe(200);
-  expect(res.body()).toEqual({
-    originalName: "test.txt",
-    filename: "file",
-    size: 5,
-    mimetype: "application/octet-stream"
-  });
-});
-```
-
-## Error Handling Examples
-
-### 404 Not Found
-```typescript
-it("GET /users/999 returns 404", async () => {
-  const res = await mockServer.get("/users/999");
-
-  expect(res.statusCode()).toBe(404);
-  expect(res.assertBodyDeepEqual({ error: "User not found" }));
-});
-```
-
-### 409 Conflict
-```typescript
-it("POST /users returns 409 for existing user", async () => {
-  const existingUser = {
-    id: 1,
-    name: "John Doe",
-    email: "john.doe@example.com",
-    age: 20
-  };
-
-  const res = await mockServer.post("/users", { body: existingUser });
-
-  expect(res.statusCode()).toBe(409);
-  expect(res.assertBodyDeepEqual({ error: "User already exists" }));
-});
-```
-
-### Server Error
-```typescript
-it("GET /users with shouldFail=true returns 500", async () => {
-  const res = await mockServer.get("/users", {
-    query: { shouldFail: "true" }
-  });
-
-  expect(res.statusCode()).toBe(500);
-});
-```
-
-## CRUD Operations Testing
-
-### Complete CRUD Test Suite
-```typescript
-describe("User CRUD Operations", () => {
-  it("creates a new user", async () => {
-    const newUser = { id: 3, name: "New User", email: "new@example.com", age: 30 };
-
-    const res = await mockServer.post("/users", { body: newUser });
-
-    expect(res.statusCode()).toBe(201);
-    expect(res.assertBodyDeepEqual(newUser));
-  });
-
-  it("reads a specific user", async () => {
-    const res = await mockServer.get("/users/1");
-
-    expect(res.statusCode()).toBe(200);
-    expect(res.assertBodySubset({ id: 1 }));
-  });
-
-  it("updates a user", async () => {
-    const res = await mockServer.patch("/users/1", {
-      body: { name: "Updated Name" }
-    });
-
-    expect(res.statusCode()).toBe(200);
-    expect(res.assertBodySubset({ id: 1, name: "Updated Name" }));
-  });
-
-  it("deletes a user", async () => {
-    const res = await mockServer.delete("/users/1");
-
-    expect(res.statusCode()).toBe(204);
-  });
-});
-```
-
-## Authentication Testing
-
-### Protected Routes
-```typescript
-describe("Authentication", () => {
-  it("accesses protected route with valid token", async () => {
-    const res = await mockServer.get("/protected", {
-      headers: { "Authorization": "Bearer valid-token" }
-    });
-
-    expect(res.statusCode()).toBe(200);
-  });
-
-  it("rejects access without token", async () => {
-    const res = await mockServer.get("/protected");
-
-    expect(res.statusCode()).toBe(401);
-  });
-
-  it("rejects access with invalid token", async () => {
-    const res = await mockServer.get("/protected", {
-      headers: { "Authorization": "Bearer invalid-token" }
-    });
-
-    expect(res.statusCode()).toBe(401);
-  });
-});
-```
-
-## Cookie Testing
-
-### Setting and Reading Cookies
-```typescript
-describe("Cookie Handling", () => {
-  it("sets session cookie on login", async () => {
-    const res = await mockServer.post("/login", {
-      body: { username: "user", password: "pass" }
-    });
-
-    expect(res.statusCode()).toBe(200);
-    expect(res.headers()["set-cookie"]).toContain("sessionId");
-  });
-
-  it("uses existing session cookie", async () => {
-    const res = await mockServer.get("/profile", {
-      cookies: { sessionId: "valid-session" }
-    });
-
-    expect(res.statusCode()).toBe(200);
-  });
-});
-```
-
-## Advanced Testing Patterns
-
-### Testing with Custom Headers
-```typescript
-it("handles custom headers", async () => {
-  const res = await mockServer.get("/api/data", {
-    headers: {
-      "X-API-Key": "secret-key",
-      "X-Client-Version": "1.0.0",
-      "Content-Type": "application/json"
-    }
-  });
-
-  expect(res.statusCode()).toBe(200);
-});
-```
-
-### Testing with IP Address
-```typescript
-it("handles IP-based logic", async () => {
-  const res = await mockServer.get("/location", {
-    ip: "192.168.1.100"
-  });
-
-  expect(res.statusCode()).toBe(200);
-  expect(res.body()).toHaveProperty("ip", "192.168.1.100");
-});
-```
-
-### Testing Query Parameters
-```typescript
-it("handles complex query parameters", async () => {
-  const res = await mockServer.get("/search", {
-    query: {
-      q: "search term",
-      category: "technology",
-      sort: "date",
-      order: "desc",
-      page: "1",
-      limit: "20"
-    }
-  });
-
-  expect(res.statusCode()).toBe(200);
-  expect(res.body()).toHaveProperty("results");
-});
-```
-
-## Testing Middleware
-
-### Rate Limiting
-```typescript
-describe("Rate Limiting", () => {
-  it("allows requests within limit", async () => {
-    const res = await mockServer.get("/api/limited");
-    expect(res.statusCode()).toBe(200);
-  });
-
-  it("blocks requests over limit", async () => {
-    // Simulate multiple requests
-    for (let i = 0; i < 10; i++) {
-      await mockServer.get("/api/limited");
-    }
-
-    const res = await mockServer.get("/api/limited");
-    expect(res.statusCode()).toBe(429);
-  });
-});
-```
-
-### CORS Testing
-```typescript
-describe("CORS", () => {
-  it("handles preflight OPTIONS request", async () => {
-    const res = await mockServer.request("OPTIONS", "/api/data", {
-      headers: {
-        "Origin": "https://example.com",
-        "Access-Control-Request-Method": "POST"
-      }
-    });
-
-    expect(res.statusCode()).toBe(200);
-    expect(res.headers()["access-control-allow-origin"]).toBe("*");
-  });
-});
-```
-
-## Performance Testing
-
-### Load Testing with MockServer
-```typescript
-describe("Performance", () => {
-  it("handles multiple concurrent requests", async () => {
-    const promises = Array.from({ length: 100 }, () =>
-      mockServer.get("/api/data")
-    );
-
-    const results = await Promise.all(promises);
-
-    results.forEach(res => {
-      expect(res.statusCode()).toBe(200);
-    });
-  });
-});
-```
-
-## Best Practices
-
-### Test Organization
-```typescript
-describe("User API", () => {
-  describe("GET /users", () => {
-    it("returns all users", async () => {
-      // Test implementation
-    });
-
-    it("supports pagination", async () => {
-      // Test implementation
-    });
-  });
-
-  describe("POST /users", () => {
-    it("creates new user", async () => {
-      // Test implementation
-    });
-
-    it("validates required fields", async () => {
-      // Test implementation
-    });
-  });
-});
-```
-
-### Type Safety
-```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-  age: number;
-}
-
-describe("Type-safe testing", () => {
-  it("returns properly typed user data", async () => {
-    const res = await mockServer.get<User[]>("/users");
-    const users = res.body() as User[];
-
-    expect(users[0]).toHaveProperty("id");
-    expect(users[0]).toHaveProperty("name");
-    expect(users[0]).toHaveProperty("email");
-  });
-});
-```
-
-These examples demonstrate the flexibility and power of MockServer for comprehensive API testing in Balda.js applications.

package/docs/docs/testing/mock-server.md

@@ -1,311 +0,0 @@
-# MockServer Testing
-
-The MockServer is Balda.js's powerful testing utility that allows you to test HTTP endpoints without starting a real server. This enables fast, isolated testing of your controllers and middleware.
-
-## Overview
-
-MockServer simulates HTTP requests by:
-- Executing the complete middleware chain
-- Running route handlers with mocked request/response objects
-- Providing realistic testing environment without network overhead
-- Supporting all HTTP methods and content types
-
-## Basic Usage
-
-```typescript
-import { describe, it, expect } from "vitest";
-import { mockServer } from "test/server/instance";
-
-describe("API Tests", () => {
-  it("GET /users returns all users", async () => {
-    const res = await mockServer.get("/users");
-    expect(res.statusCode()).toBe(200);
-    expect(Array.isArray(res.body())).toBe(true);
-  });
-});
-```
-
-## HTTP Methods
-
-MockServer provides methods for all HTTP verbs:
-
-### GET Requests
-```typescript
-// Simple GET request
-const res = await mockServer.get("/users");
-
-// GET with query parameters
-const res = await mockServer.get("/users", {
-  query: { page: "1", limit: "10" }
-});
-
-// GET with headers
-const res = await mockServer.get("/users", {
-  headers: { "Authorization": "Bearer token123" }
-});
-```
-
-### POST Requests
-```typescript
-// POST with JSON body
-const res = await mockServer.post("/users", {
-  body: { name: "John", email: "john@example.com" }
-});
-
-// POST with form data
-const res = await mockServer.post("/users", {
-  urlencoded: { name: "John", email: "john@example.com" }
-});
-
-// POST with file upload
-const formData = new FormData();
-formData.append("file", new Blob(["content"]), "test.txt");
-const res = await mockServer.post("/upload", { formData });
-```
-
-### Other HTTP Methods
-```typescript
-// PUT request
-const res = await mockServer.put("/users/1", {
-  body: { name: "Updated Name" }
-});
-
-// PATCH request
-const res = await mockServer.patch("/users/1", {
-  body: { name: "Patched Name" }
-});
-
-// DELETE request
-const res = await mockServer.delete("/users/1");
-```
-
-## Request Options
-
-MockServer supports comprehensive request configuration:
-
-```typescript
-interface MockServerOptions {
-  headers?: Record<string, string>;
-  query?: Record<string, string>;
-  cookies?: Record<string, string>;
-  ip?: string;
-  body?: any;
-  formData?: FormData;
-  urlencoded?: Record<string, string>;
-}
-```
-
-### Headers
-```typescript
-const res = await mockServer.get("/protected", {
-  headers: {
-    "Authorization": "Bearer token123",
-    "Content-Type": "application/json"
-  }
-});
-```
-
-### Query Parameters
-```typescript
-const res = await mockServer.get("/search", {
-  query: {
-    q: "search term",
-    page: "1",
-    limit: "20"
-  }
-});
-```
-
-### Cookies
-```typescript
-const res = await mockServer.get("/profile", {
-  cookies: {
-    sessionId: "abc123",
-    userId: "456"
-  }
-});
-```
-
-### IP Address
-```typescript
-const res = await mockServer.get("/location", {
-  ip: "192.168.1.1"
-});
-```
-
-## Response Assertions
-
-MockResponse provides powerful assertion methods:
-
-### Status Code Assertions
-```typescript
-const res = await mockServer.get("/users");
-expect(res.statusCode()).toBe(200);
-expect(res.assertStatus(200)); // Alternative syntax
-```
-
-### Body Assertions
-```typescript
-// Exact body match
-expect(res.assertBodyDeepEqual({ id: 1, name: "John" }));
-
-// Partial body match
-expect(res.assertBodySubset({ name: "John" }));
-
-// Get body content
-const body = res.body();
-expect(body.name).toBe("John");
-```
-
-### Complete Example
-```typescript
-describe("User API", () => {
-  it("creates a new user", async () => {
-    const newUser = {
-      name: "Jane Doe",
-      email: "jane@example.com",
-      age: 25
-    };
-
-    const res = await mockServer.post("/users", { body: newUser });
-
-    expect(res.assertStatus(201));
-    expect(res.assertBodyDeepEqual(newUser));
-  });
-
-  it("returns 404 for non-existent user", async () => {
-    const res = await mockServer.get("/users/999");
-
-    expect(res.assertStatus(404));
-    expect(res.assertBodyDeepEqual({ error: "User not found" }));
-  });
-});
-```
-
-## File Upload Testing
-
-MockServer supports file upload testing with FormData:
-
-```typescript
-describe("File Upload", () => {
-  it("uploads a file successfully", async () => {
-    const formData = new FormData();
-    const fileContent = new Uint8Array([1, 2, 3, 4, 5]);
-    formData.append("file", new Blob([fileContent]), "test.txt");
-
-    const res = await mockServer.post("/upload", { formData });
-
-    expect(res.assertStatus(200));
-    expect(res.body()).toEqual({
-      originalName: "test.txt",
-      filename: "file",
-      size: 5,
-      mimetype: "application/octet-stream"
-    });
-  });
-});
-```
-
-## Error Handling
-
-MockServer properly handles and reports errors:
-
-```typescript
-describe("Error Handling", () => {
-  it("handles server errors gracefully", async () => {
-    const res = await mockServer.get("/users", {
-      query: { shouldFail: "true" }
-    });
-
-    expect(res.assertStatus(500));
-    expect(res.body()).toHaveProperty("error");
-  });
-});
-```
-
-## Best Practices
-
-### 1. Test Isolation
-```typescript
-describe("User Management", () => {
-  // Each test should be independent
-  it("creates user", async () => {
-    // Test implementation
-  });
-
-  it("updates user", async () => {
-    // Test implementation - doesn't depend on previous test
-  });
-});
-```
-
-### 2. Descriptive Test Names
-```typescript
-// Good
-it("POST /users returns 409 when user already exists", async () => {
-  // Test implementation
-});
-
-// Avoid
-it("test user creation", async () => {
-  // Test implementation
-});
-```
-
-### 3. Use TypeScript
-```typescript
-interface UserResponse {
-  id: number;
-  name: string;
-  email: string;
-}
-
-const res = await mockServer.get<UserResponse[]>("/users");
-const users = res.body() as UserResponse[];
-```
-
-### 4. Test Edge Cases
-```typescript
-describe("User Validation", () => {
-  it("rejects invalid email format", async () => {
-    const res = await mockServer.post("/users", {
-      body: { name: "John", email: "invalid-email" }
-    });
-
-    expect(res.assertStatus(400));
-  });
-
-  it("requires all mandatory fields", async () => {
-    const res = await mockServer.post("/users", {
-      body: { name: "John" } // Missing email
-    });
-
-    expect(res.assertStatus(400));
-  });
-});
-```
-
-## Advanced Features
-
-### Custom Request Configuration
-```typescript
-const res = await mockServer.request("GET", "/api/data", {
-  headers: {
-    "X-Custom-Header": "value",
-    "Authorization": "Bearer token"
-  },
-  query: { filter: "active" },
-  cookies: { sessionId: "abc123" },
-  ip: "192.168.1.100"
-});
-```
-
-### Testing Middleware
-MockServer executes the complete middleware chain, allowing you to test:
-- Authentication middleware
-- Rate limiting
-- CORS handling
-- Request logging
-- Custom business logic middleware
-
-This comprehensive testing approach ensures your entire request pipeline works correctly in isolation.