git:20260527.808710c to git:20260818.2ff7b22

---

name: simba-testing

description: Guide for testing Simba distributed lock and leader-election code. Use when writing or reviewing tests for MutexContender, SimbaLocker, AbstractScheduler, backend TCK conformance via MutexContendServiceSpec, Redis/JDBC/Zookeeper integration tests, timing-sensitive lock behavior, or new Kotlin assertions in Simba-based code.

---

# Testing Simba-Based Code

## Test Strategy Overview

Simba testing has three layers:

1. **Unit tests** — mock the `MutexContendServiceFactory`, test your business logic in isolation

2. **TCK (Technology Compatibility Kit)** — extend `MutexContendServiceSpec` to verify a backend implementation

3. **Integration tests** — run against a real backend (Redis, MySQL, Zookeeper)

Choose the simplest layer that gives confidence. Most application code only needs unit tests with mocks. Backend implementors need TCK + integration tests.

Before writing a test, decide:

- **Backend implementation**: extend `MutexContendServiceSpec` and run against the real backend.

- **Scheduler behavior**: verify leadership gating separately from the business logic in `work()`.

## Unit Tests with MockK

```kotlin

import io.mockk.every

import io.mockk.mockk

import io.mockk.verify

import me.ahoo.simba.core.MutexContendService

import me.ahoo.simba.core.MutexContendServiceFactory

import me.ahoo.simba.core.MutexContender

import me.ahoo.simba.core.MutexOwner

import me.ahoo.simba.core.MutexState

private val mockFactory = mockk<MutexContendServiceFactory>()

private val mockService = mockk<MutexContendService>(relaxed = true)

@BeforeEach

fun setup() {

every { mockFactory.createMutexContendService(any()) } returns mockService

}

@Test

fun `should start contend service`() {

}

}

```

### Simulating Leadership Changes

```kotlin

@Test

fun `should react to leadership change`() {

val contenderSlot = slot<MutexContender>()

every { mockFactory.createMutexContendService(capture(contenderSlot)) } returns mockService

// Create your service/component that uses Simba

val myComponent = MyComponent(mockFactory)

myComponent.start()

// Simulate acquiring leadership

// Assert your component's behavior

myComponent.isLeader.assert().isTrue()

// Simulate losing leadership

myComponent.isLeader.assert().isFalse()

}

```

### SimbaLocker Unit Tests

Mock the factory and verify the locker lifecycle:

```kotlin

import me.ahoo.simba.locker.SimbaLocker

@Test

val mockService = mockk<MutexContendService>(relaxed = true)

every { mockFactory.createMutexContendService(any()) } returns mockService

val locker = SimbaLocker("test-lock", mockFactory)

locker.close()

verify { mockService.stop() }

}

```

## TCK — Extending MutexContendServiceSpec

When implementing a new Simba backend, extend the TCK to verify correctness:

```kotlin

import me.ahoo.simba.test.MutexContendServiceSpec

class MyBackendMutexContendServiceTest : MutexContendServiceSpec() {

override val mutexContendServiceFactory: MutexContendServiceFactory =

MyBackendMutexContendServiceFactory(/* dependencies */)

}

```

This gives you five standard tests:

1. **`start()`** — acquire, verify owner, stop, verify released

2. **`restart()`** — stop and restart, verify full lifecycle repeats

3. **`guard()`** — acquire, wait 3s, verify owner hasn't changed (TTL renewal works)

4. **`multiContend()`** — 10 contenders compete, exactly one owner at any time

5. **`schedule()`** — AbstractScheduler lifecycle, work executes on leader

### Backend-Specific Test Requirements

| Backend | External dependency | Notes |

|---------|-------------------|-------|

| Redis | Running Redis instance | Current repository tests use `RedisStandaloneConfiguration` defaults |

| JDBC | Running MySQL instance | Current repository tests use `jdbc:mysql://localhost:3306/simba_db`, `root`/`root`; init script: `simba-jdbc/src/init-script/init-simba-mysql.sql` |

| Zookeeper | None | Uses Curator's `TestingServer` (embedded) |

Do not silently add Testcontainers to this repository's tests. If CI isolation is required, add the dependency and Gradle wiring intentionally, then update the backend setup code and this skill together.

## AbstractScheduler Tests

Test that scheduled work runs only on the leader:

```kotlin

import me.ahoo.simba.schedule.AbstractScheduler

import me.ahoo.simba.schedule.ScheduleConfig

@Test

fun `scheduler should run work only when leader`() {

val scheduler = object : AbstractScheduler("test-scheduler", mockFactory) {

override val config = ScheduleConfig.delay(Duration.ZERO, Duration.ofMillis(100))

override val worker = "test"

override fun work() {

}

}

scheduler.start()

}

```

## Assertion Style

Use `fluent-assert` for new Kotlin assertions:

```kotlin

import me.ahoo.test.asserts.assert

value.assert().isEqualTo(expected)

collection.assert().hasSize(3)

bool.assert().isTrue()

```

Do not churn existing Hamcrest/AssertJ assertions solely for style. When adding or touching assertions, prefer `.assert()` and keep the local test readable.

## Common Test Pitfalls

1. **Timing-dependent tests**: Distributed lock tests are inherently timing-sensitive. Use generous timeouts (5-30s) and prefer `CountDownLatch` / `CompletableFuture` over new `Thread.sleep` calls.

2. **Shared mutex names**: Each test should use a unique mutex name to avoid cross-test interference. Use `"test-mutex-${UUID.randomUUID()}"`.

3. **Resource cleanup**: Always stop/close services in `@AfterEach` to avoid leaked threads and held locks.

4. **Mocking `MutexContendService` vs `MutexContendServiceFactory`**: Mock the factory (the DI seam), not the service directly. The factory is what application code injects.

5. **Testing `AbstractScheduler` without Simba**: If you only need to test the `work()` method, call it directly. The scheduler pattern is about leadership gating, not the work itself.