testing

name	testing
description	Testing guidelines. Use when writing or updating tests.
metadata	{"short-description":"Testing guidelines."}

Testing

Creating tests

Docs: https://docs.adonisjs.com/guides/testing/introduction

• Tests are located in tests/ and are based on AdonisJS Japa library
• New tests are created with the command node ace make:test --suite=<functional|browser|unit>
• Tests are run with LOG_LEVEL=info node ace test functional|browser|unit
  • Run a specific group of test with node ace test --groups=""
• Global database setup belongs in tests/bootstrap.ts via testUtils.db().migrate()
• Create a new test user (and organization when needed) per test group via test helpers like createTestActors from tests/utils/test_actors.ts; do not reuse shared actors
• Tests should have descriptive snake_case names that make it obvious what they test when looking at the test runner
• Do not add console logs or any other explicit reporting when output is missing
• If your service is dependent on other services, those can be instantiated for testing with await app.container.make(ClassName)
• Tests that mutate db data should be reset between individual tests using testUtils.db().withGlobalTransaction():

test.group('User', (group) => {
  group.each.setup(() => testUtils.db().withGlobalTransaction())
})

• If you are configuring standalone tests from tests/bootstrap.ts, use suite-level wiring that adds test.setup(() => testUtils.db().withGlobalTransaction()) for each test in the suite.
• The global transaction approach will not work if the code under test manages its own transactions. In that case, use testUtils.db().truncate() instead so tables are cleared after each test.

import { test } from '@japa/runner'

test.group('User', (group) => {
  group.each.setup(() => testUtils.db().truncate())
})

AdonisJS Testing Guidelines

Philosophy: Fakes for Internal, Mocks for External

Core Principle: Use Fakes via Dependency Injection (container.swap) for testing interactions between your internal application services.

Why Fakes?

• Promotes test isolation, speed, and control
• Encourages designing services with clear, testable interfaces
• If mocking an internal service feels complex, consider refactoring the service's interface for simplicity

When to Mock? Reserve mocking primarily for truly external systems (e.g., third-party HTTP APIs) where a fake implementation isn't practical.

Faking Internal Service Dependencies

Mechanism

app.container.swap(ServiceIdentifier, () => new FakeService())

Creating Fakes

Define a simple FakeService class. It can extend the original service or simply implement the necessary methods/properties used by the Service Under Test (SUT). Only override methods critical for the test scenario.

Observing Interactions with Fakes

Since you define the FakeService, you control its implementation. Add properties or methods to your fake class to track calls:

• Store arguments passed to faked methods (e.g., this.lastArgs = args or this.calls.push(args))
• Use simple flags (e.g., this.methodWasCalled = true)
• Maintain internal state relevant to the test if needed

Accessing the Fake: Keep a reference to the instance of the FakeService you create before passing its factory function to swap. Use this reference in your assertions.

Test Lifecycle

• Swap the dependency within the specific test or in group.each.setup.
• Crucially: Restore the original implementation using app.container.restore(ServiceIdentifier) or app.container.restoreAll() in test.cleanup or group.each.teardown.

Example

// Scenario: A UserService calls NotificationService.sendWelcomeEmail(user) upon registration

// Create a fake NotificationService
class FakeNotificationService extends NotificationService {
  public sendWelcomeEmailCalled = false
  public welcomeEmailUser: User | null = null

  async sendWelcomeEmail(user: User) {
    this.sendWelcomeEmailCalled = true
    this.welcomeEmailUser = user
    // Don't actually send an email
  }

  // Other methods can be omitted or throw if unexpected calls occur
}

// Test using the fake
test('registration sends welcome email', async ({ assert }) => {
  const fakeNotifier = new FakeNotificationService()
  app.container.swap(NotificationService, () => fakeNotifier)

  const userService = await app.container.make(UserService)
  const newUser = await userService.register({ email: '[e-mail]' /* ... */ })

  assert.isTrue(fakeNotifier.sendWelcomeEmailCalled)
  assert.equal(fakeNotifier.welcomeEmailUser?.id, newUser.id)
  assert.equal(fakeNotifier.welcomeEmailUser?.email, '[e-mail]')

  // Remember to restore
  app.container.restore(NotificationService)
})

Testing Services Interacting with the Database

Isolation

Run migrations once globally, then wrap database-mutating tests in per-test transactions:

export const runnerHooks: Required<Pick<Config, 'setup' | 'teardown'>> = {
  setup: [() => testUtils.db().migrate()],
  teardown: [],
}

SUT Uses DB Directly

If your Service Under Test directly interacts with the database, test the real service implementation. Rely on the DB transaction for cleanup and isolation.

test('user service stores user in DB', async ({ assert }) => {
  const userService = await app.container.make(UserService)
  const newUser = await userService.register({ username: 'testuser' })

  // Assert user was properly stored
  assert.isNotNull(newUser.id)

  // Verify with a direct DB query
  const storedUser = await User.findOrFail(newUser.id)
  assert.equal(storedUser.username, 'testuser')
})

SUT Depends on a DB-Interacting Service

Fake the dependency service using container.swap. The fake should return predefined data to simulate the dependency's database operation. This isolates the SUT from any DB interactions of its dependencies.

test('quota service properly updates user credit balance', async ({ assert }) => {
  // Fake the transaction service that normally writes to DB
  class FakeTransactionService {
    public lastTransaction = null

    async createTransaction(data) {
      this.lastTransaction = data
      return { id: 'fake-tx-123', ...data }
    }
  }

  const fakeTransactions = new FakeTransactionService()
  app.container.swap('transactions', () => fakeTransactions)

  // Service under test
  const quotaService = await app.container.make(MonthlyQuotaService)
  const user = testUser
  const quota = await MonthlyCreditQuota.create({
    userId: user.id,
    maxSummaryCredits: 10000,
    spentSummaryCredits: 4000,
    nextUsageReset: DateTime.now().minus({ days: 1 }),
  })

  await quotaService.updateQuota({ quota: quota.id })

  // Assert transaction was created with correct data
  assert.equal(fakeTransactions.lastTransaction.userId, user.id)
  assert.equal(fakeTransactions.lastTransaction.summaryCredits, 4000)

  // Restore original service
  app.container.restore('transactions')
})

Mocking External Network Requests (fetch)

When

Use this when your service makes HTTP requests to external, third-party APIs.

Tool

Use undici's MockAgent. It's the library powering Node.js's fetch and provides built-in mocking capabilities.

Mechanism

import { MockAgent, setGlobalDispatcher } from 'undici'

test('weather service fetches and processes data correctly', async ({ assert }) => {
  // Setup mock agent
  const agent = new MockAgent()
  setGlobalDispatcher(agent)

  // Setup intercept
  agent
    .get('https://api.weather.com')
    .intercept({
      path: '/forecast',
      method: 'GET',
      query: { city: 'oslo' },
    })
    .reply(200, {
      temperature: 5,
      condition: 'sunny',
    })

  // Test service
  const weatherService = await app.container.make(WeatherService)
  const forecast = await weatherService.getForecast('oslo')

  // Assert
  assert.equal(forecast.temperature, 5)
  assert.equal(forecast.condition, 'sunny')

  // Cleanup
  agent.close()
})

Leveraging AdonisJS Built-in Fakes

AdonisJS provides official fakes for common modules:

• Emitter fake
• Hash fake
• Fake mailer
• Drive fake

Use these when testing interactions with those specific modules for convenience.

Testing Time-Sensitive Logic

Tool

Use timekeeper for predictable control over Date.

Example

import timekeeper from 'timekeeper'

test('expired tokens are rejected', async ({ assert }) => {
  // Create token that expires in 10 minutes
  const tokenService = await app.container.make(TokenService)
  const token = await tokenService.create(testUser.id, { expiresInMinutes: 10 })

  // Travel 30 minutes into the future
  const futureTime = new Date()
  futureTime.setMinutes(futureTime.getMinutes() + 30)
  timekeeper.travel(futureTime)

  // Assert token is now expired
  assert.isFalse(await tokenService.verify(token))

  // Reset time
  timekeeper.reset()
})

To avoid boilerplate, create a test helper:

// in test_helpers.ts
import { getActiveTest } from '@japa/runner'
import timekeeper from 'timekeeper'

export function timeTravel(minutesToTravel: number) {
  const test = getActiveTest()
  if (!test) {
    throw new Error('Cannot use "timeTravel" outside of a Japa test')
  }

  timekeeper.reset()

  const date = new Date()
  date.setMinutes(date.getMinutes() + minutesToTravel)
  timekeeper.travel(date)

  test.cleanup(() => {
    timekeeper.reset()
  })
}