Genric message

Author: goldbergyoni

.github/instructions/testing.instructions.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This repository contains a comprehensive guide and examples for Node.js testing best practices, focusing on integration/component testing. It includes both educational content and a practical example application that demonstrates modern testing techniques.
+
+## Commands
+
+### Testing
+- `npm test` - Run Jest tests (default test runner)
+- `npm run test:vitest` - Run Vitest tests (alternative test runner)
+- `npm run test:dev` - Run Jest in watch mode with optimized settings (2 workers, silent)
+- `npm run test:dev:debug` - Run Jest in debug mode with inspector on port 9229
+- `npm run test:dev:verbose` - Run Jest in watch mode with verbose output
+- `npm run test:nestjs` - Run NestJS-specific tests
+
+### Database
+- `npm run db:migrate` - Run database migrations (uses Sequelize CLI)
+- `npm run db:seed` - Seed database with initial data
+
+### Code Quality
+- `npm run lint` - Run ESLint on the codebase
+
+## Architecture
+
+### Example Application Structure
+The repository contains an example Node.js application demonstrating testing best practices:
+
+- **Entry Points** (`example-application/entry-points/`): API server (Express.js) and message queue consumer
+- **Business Logic** (`example-application/business-logic/`): Core order service logic
+- **Data Access** (`example-application/data-access/`): Database repository layer with Sequelize ORM
+- **Libraries** (`example-application/libraries/`): Shared utilities (authentication, logging, message queue client, etc.)
+
+### Testing Architecture
+
+**Dual Test Framework Support:**
+- **Jest** (primary): Configured in `jest.config.js` with comprehensive watch plugins
+- **Vitest** (alternative): Configured in `vitest.config.ts` for modern ESM support
+
+**Test Organization:**
+- Jest tests: `example-application/test/jest/*.test.ts`
+- Vitest tests: `example-application/test/vitest/*.spec.ts`
+- Setup files: `example-application/test/setup/`
+
+**Infrastructure Setup:**
+- Docker Compose for PostgreSQL database (port 54310)
+- Global setup automatically starts database if not running
+- Database migrations and seeding via npm scripts
+- Smart cleanup: database persists in dev, cleaned up in CI
+
+**Testing Philosophy:**
+- **Component/Integration First**: Tests focus on entire API endpoints with real database
+- **Minimal E2E**: Only 3-10 E2E tests for configuration/infrastructure issues
+- **Selective Unit Tests**: Only for complex algorithms or non-trivial logic
+- **Feature-Focused**: Tests cover features/routes, not individual functions
+
+### Key Patterns
+
+**Database Testing:**
+- Tests use real PostgreSQL database, not mocks
+- Global setup handles Docker container lifecycle
+- Database cleanup occurs probabilistically (10% chance) in dev, always in CI
+- Migration and seeding handled by npm scripts
+
+**Test Data:**
+- Data factories in `example-application/test/order-data-factory.ts`
+- Metadata seeded once, test data created per test
+- No shared test data between tests
+
+**Error Handling:**
+- Centralized error handler in `example-application/error-handling.js`
+- Process-level uncaught exception/rejection handling
+
+## Development Notes
+
+- The repository demonstrates the "Testing Diamond" strategy prioritizing component tests
+- Anti-pattern examples are excluded from test runs by default (see jest.config.js)
+- Performance tests are also excluded by default
+- TypeScript support with ts-jest transformer
+- Rich Jest watch mode with plugins for filtering, repeating, and suspending tests

CLAUDE.md

@@ -62,6 +62,72 @@ module.exports.getOrder = async function (id) {
   return await new OrderRepository().getOrderById(id);
 };
 
+module.exports.updateOrder = async function (id, orderUpdates) {
+  await validateUpdateRequest(id, orderUpdates);
+  
+  const existingOrder = await getExistingOrder(id);
+  await validateUserIfUpdated(orderUpdates, existingOrder);
+  
+  const processedUpdates = applyBusinessLogic(orderUpdates, existingOrder);
+  
+  return await new OrderRepository().updateOrder(id, processedUpdates);
+};
+
+async function validateUpdateRequest(id, orderUpdates) {
+  if (!id) {
+    throw new AppError('invalid-id', 'No order ID specified', 400);
+  }
+
+  if (!orderUpdates || Object.keys(orderUpdates).length === 0) {
+    throw new AppError('invalid-update', 'No update data provided', 400);
+  }
+
+  if (orderUpdates.id !== undefined) {
+    throw new AppError('invalid-field', 'Cannot update order ID', 400);
+  }
+
+  if (orderUpdates.productId !== undefined && !orderUpdates.productId) {
+    throw new AppError('invalid-order', 'Product ID cannot be empty', 400);
+  }
+}
+
+async function getExistingOrder(id) {
+  const existingOrder = await new OrderRepository().getOrderById(id);
+  if (!existingOrder) {
+    throw new AppError('order-not-found', `Order with ID ${id} not found`, 404);
+  }
+  return existingOrder;
+}
+
+async function validateUserIfUpdated(orderUpdates, existingOrder) {
+  if (orderUpdates.userId !== undefined && orderUpdates.userId !== existingOrder.userId) {
+    const userWhoOrdered = await getUserFromUsersService(orderUpdates.userId);
+    if (!userWhoOrdered) {
+      throw new AppError(
+        'user-doesnt-exist',
+        `The user ${orderUpdates.userId} doesnt exist`,
+        404,
+      );
+    }
+  }
+}
+
+function applyBusinessLogic(orderUpdates, existingOrder) {
+  const processedUpdates = { ...orderUpdates };
+  
+  if (processedUpdates.totalPrice !== undefined) {
+    const isPremium = processedUpdates.isPremiumUser !== undefined 
+      ? processedUpdates.isPremiumUser 
+      : existingOrder.isPremiumUser;
+    
+    if (isPremium) {
+      processedUpdates.totalPrice = Math.ceil(processedUpdates.totalPrice * 0.9);
+    }
+  }
+  
+  return processedUpdates;
+}
+
 async function getUserFromUsersService(userId) {
   try {
     const getUserResponse = await axiosHTTPClient.get(

example-application/business-logic/order-service.js

@@ -61,6 +61,14 @@ module.exports = class OrderRepository {
     return;
   }
 
+  async updateOrder(id, orderDetails) {
+    await orderModel.update(orderDetails, {
+      where: { id },
+    });
+    
+    return await this.getOrderById(id);
+  }
+
   async cleanup() {
     await orderModel.truncate();
   }

example-application/data-access/order-repository.js

@@ -77,6 +77,17 @@ const defineRoutes = (expressApp: express.Application) => {
     res.json(response);
   });
 
+  // update order by id
+  router.put('/:id', async (req, res, next) => {
+    try {
+      console.log(`Order API was called to update order ${req.params.id} with ${util.inspect(req.body)}`);
+      const updatedOrder = await orderService.updateOrder(req.params.id, req.body);
+      res.json(updatedOrder);
+    } catch (error) {
+      next(error);
+    }
+  });
+
   // delete order by id
   router.delete('/:id', async (req, res, next) => {
     console.log(`Order API was called to delete order ${req.params.id}`);

example-application/entry-points/api.ts

@@ -0,0 +1,177 @@
+import { buildOrder } from '../order-data-factory';
+import { testSetup } from '../setup/test-file-setup';
+
+beforeAll(async () => {
+  await testSetup.start({
+    startAPI: true,
+    disableNetConnect: true,
+    includeTokenInHttpClient: true,
+    mockGetUserCalls: true,
+    mockMailerCalls: true,
+  });
+});
+
+beforeEach(() => {
+  testSetup.resetBeforeEach();
+});
+
+afterAll(async () => {
+  testSetup.tearDownTestFile();
+});
+
+describe('PUT /order/:id', () => {
+  test('When updating an existing order with valid data, Then should return updated order', async () => {
+    // Arrange
+    const originalOrder = buildOrder();
+    const { data: createdOrder } = await testSetup.getHTTPClienForArrange().post('/order', originalOrder);
+    const updates = {
+      totalPrice: 150,
+      mode: 'pending',
+      contactEmail: 'updated@example.com'
+    };
+
+    // Act
+    const updateResponse = await testSetup.getHTTPClient().put(`/order/${createdOrder.id}`, updates);
+
+    // Assert
+    expect(updateResponse.status).toBe(200);
+    expect(updateResponse.data).toMatchObject({
+      id: createdOrder.id,
+      userId: originalOrder.userId,
+      productId: originalOrder.productId,
+      isPremiumUser: originalOrder.isPremiumUser,
+      externalIdentifier: originalOrder.externalIdentifier,
+      ...updates,
+    });
+  });
+
+  test('When updating premium user order with new price, Then should apply discount', async () => {
+    // Arrange
+    const originalOrder = buildOrder({ isPremiumUser: true, totalPrice: 100 });
+    const { data: createdOrder } = await testSetup.getHTTPClienForArrange().post('/order', originalOrder);
+    const updates = { totalPrice: 200 };
+
+    // Act
+    const updateResponse = await testSetup.getHTTPClient().put(`/order/${createdOrder.id}`, updates);
+
+    // Assert
+    expect(updateResponse.status).toBe(200);
+    expect(updateResponse.data.totalPrice).toBe(180); // 200 * 0.9 = 180
+  });
+
+  test('When updating order to premium user, Then existing price should not change', async () => {
+    // Arrange
+    const originalOrder = buildOrder({ isPremiumUser: false, totalPrice: 100 });
+    const { data: createdOrder } = await testSetup.getHTTPClienForArrange().post('/order', originalOrder);
+    const updates = { isPremiumUser: true };
+
+    // Act
+    const updateResponse = await testSetup.getHTTPClient().put(`/order/${createdOrder.id}`, updates);
+
+    // Assert
+    expect(updateResponse.status).toBe(200);
+    expect(updateResponse.data.totalPrice).toBe(100); // Price unchanged since totalPrice not updated
+    expect(updateResponse.data.isPremiumUser).toBe(true);
+  });
+
+  test('When updating both price and premium status, Then should apply discount', async () => {
+    // Arrange
+    const originalOrder = buildOrder({ isPremiumUser: false, totalPrice: 100 });
+    const { data: createdOrder } = await testSetup.getHTTPClienForArrange().post('/order', originalOrder);
+    const updates = { isPremiumUser: true, totalPrice: 200 };
+
+    // Act
+    const updateResponse = await testSetup.getHTTPClient().put(`/order/${createdOrder.id}`, updates);
+
+    // Assert
+    expect(updateResponse.status).toBe(200);
+    expect(updateResponse.data.totalPrice).toBe(180); // 200 * 0.9 = 180
+    expect(updateResponse.data.isPremiumUser).toBe(true);
+  });
+
+  test('When updated order can be retrieved, Then should return the updated data', async () => {
+    // Arrange
+    const originalOrder = buildOrder();
+    const { data: createdOrder } = await testSetup.getHTTPClienForArrange().post('/order', originalOrder);
+    const updates = { mode: 'cancelled', contactEmail: 'cancelled@example.com' };
+
+    // Act
+    await testSetup.getHTTPClient().put(`/order/${createdOrder.id}`, updates);
+    
+    // Assert - verify state persistence
+    const getResponse = await testSetup.getHTTPClient().get(`/order/${createdOrder.id}`);
+    expect(getResponse.status).toBe(200);
+    expect(getResponse.data).toMatchObject({
+      id: createdOrder.id,
+      userId: originalOrder.userId,
+      productId: originalOrder.productId,
+      isPremiumUser: originalOrder.isPremiumUser,
+      externalIdentifier: originalOrder.externalIdentifier,
+      ...updates,
+    });
+  });
+});
+
+describe('PUT /order/:id - Validation Tests', () => {
+  test('When updating non-existent order, Then should return 404', async () => {
+    // Arrange
+    const nonExistentId = 99999;
+    const updates = { mode: 'pending' };
+
+    // Act & Assert
+    const updateResponse = await testSetup.getHTTPClient().put(`/order/${nonExistentId}`, updates);
+    expect(updateResponse.status).toBe(404);
+  });
+
+  test('When updating with empty data, Then should return 400', async () => {
+    // Arrange
+    const originalOrder = buildOrder();
+    const { data: createdOrder } = await testSetup.getHTTPClienForArrange().post('/order', originalOrder);
+
+    // Act & Assert
+    const updateResponse = await testSetup.getHTTPClient().put(`/order/${createdOrder.id}`, {});
+    expect(updateResponse.status).toBe(400);
+  });
+
+  test('When trying to update order ID, Then should return 400', async () => {
+    // Arrange
+    const originalOrder = buildOrder();
+    const { data: createdOrder } = await testSetup.getHTTPClienForArrange().post('/order', originalOrder);
+    const updates = { id: 12345, mode: 'pending' };
+
+    // Act & Assert
+    const updateResponse = await testSetup.getHTTPClient().put(`/order/${createdOrder.id}`, updates);
+    expect(updateResponse.status).toBe(400);
+  });
+
+  test('When updating with empty productId, Then should return 400', async () => {
+    // Arrange
+    const originalOrder = buildOrder();
+    const { data: createdOrder } = await testSetup.getHTTPClienForArrange().post('/order', originalOrder);
+    const updates = { productId: null };
+
+    // Act & Assert
+    const updateResponse = await testSetup.getHTTPClient().put(`/order/${createdOrder.id}`, updates);
+    expect(updateResponse.status).toBe(400);
+  });
+
+  test('When updating with non-existent userId, Then should return 404', async () => {
+    // Arrange
+    const originalOrder = buildOrder();
+    const { data: createdOrder } = await testSetup.getHTTPClienForArrange().post('/order', originalOrder);
+    const updates = { userId: 99999 };
+
+    // Act & Assert
+    const updateResponse = await testSetup.getHTTPClient().put(`/order/${createdOrder.id}`, updates);
+    expect(updateResponse.status).toBe(404);
+  });
+
+  test('When updating without order ID in URL, Then should return 404', async () => {
+    // Arrange
+    const updates = { mode: 'pending' };
+
+    // Act & Assert
+    const updateResponse = await testSetup.getHTTPClient().put('/order/', updates);
+    expect(updateResponse.status).toBe(404); // Express returns 404 for missing route parameter
+  });
+});