Test Organisation

Jest test file structure with AAA and shared setup

// src/services/orderService.test.ts (co-located with orderService.ts)
import { OrderService } from './orderService';
import { createOrder, createUser } from '../test/factories';
import { prismaMock } from '../test/prisma-mock';

describe('OrderService', () => {
  let service: OrderService;

  beforeEach(() => {
    service = new OrderService(prismaMock);
  });

  describe('placeOrder', () => {
    it('creates an order with confirmed status when items are valid', async () => {
      // Arrange
      const user = createUser({ id: 'usr-1' });
      const items = [{ productId: 'prod-1', qty: 2, unitPrice: 1999 }];
      prismaMock.order.create.mockResolvedValue(createOrder({ status: 'confirmed' }));

      // Act
      const result = await service.placeOrder({ userId: user.id, items });

      // Assert
      expect(result.status).toBe('confirmed');
      expect(prismaMock.order.create).toHaveBeenCalledWith(
        expect.objectContaining({ data: expect.objectContaining({ userId: 'usr-1' }) })
      );
    });

    it('throws OrderError when items array is empty', async () => {
      await expect(
        service.placeOrder({ userId: 'usr-1', items: [] })
      ).rejects.toThrow('Order must contain at least one item');
    });
  });
});

Co-locating test files eliminates the parallel test directory structure that falls out of sync. prismaMock (jest-mock-extended) provides type-safe mocks that fail if the Prisma schema changes and the mock is not updated.

RSpec shared contexts and factory organisation

# spec/support/shared_contexts/authenticated_user.rb
RSpec.shared_context 'authenticated user' do
  let(:user) { create(:user, :verified) }
  let(:auth_headers) { { 'Authorization' => "Bearer #{user.auth_token}" } }
end

# spec/support/factories/order_factory.rb (FactoryBot)
FactoryBot.define do
  factory :order do
    association :customer, factory: :user
    status { :draft }
    currency { 'USD' }

    trait :with_items do
      after(:create) do |order|
        create_list(:order_item, 3, order: order)
      end
    end

    trait :placed do
      status { :placed }
      placed_at { 1.hour.ago }
    end
  end
end

# spec/requests/orders_spec.rb
RSpec.describe 'Orders API', type: :request do
  include_context 'authenticated user'

  describe 'POST /api/v1/orders' do
    context 'with valid items' do
      it 'returns 201 and the created order' do
        post '/api/v1/orders',
          params: { items: [{ product_id: 1, qty: 2 }] },
          headers: auth_headers
        expect(response).to have_http_status(:created)
        expect(json_response['data']['status']).to eq('draft')
      end
    end
  end
end

shared_context reuses authentication setup across request specs without duplication. FactoryBot traits compose factory variations; :placed can be combined with :with_items. create_list inside after(:create) builds associations correctly after the parent is persisted.