Testing Android Code - Bitwarden Testing Patterns

This skill provides tactical testing guidance for Bitwarden-specific patterns. For comprehensive architecture and testing philosophy, consult docs/ARCHITECTURE.md .

Test Framework Configuration

Required Dependencies:

• JUnit 5 (jupiter), MockK, Turbine (app.cash.turbine)

• kotlinx.coroutines.test, Robolectric, Compose Test

Critical Note: Tests run with en-US locale for consistency. Don't assume other locales.

A. ViewModel Testing Patterns

Base Class: BaseViewModelTest

Always extend BaseViewModelTest for ViewModel tests.

Location: ui/src/testFixtures/kotlin/com/bitwarden/ui/platform/base/BaseViewModelTest.kt

Benefits:

• Automatically registers MainDispatcherExtension for UnconfinedTestDispatcher

• Provides stateEventFlow() helper for simultaneous StateFlow/EventFlow testing

Pattern:

class ExampleViewModelTest : BaseViewModelTest() { private val mockRepository: ExampleRepository = mockk() private val savedStateHandle = SavedStateHandle(mapOf(KEY_STATE to INITIAL_STATE))

@Test
fun `ButtonClick should fetch data and update state`() = runTest {
    coEvery { mockRepository.fetchData(any()) } returns Result.success("data")

    val viewModel = ExampleViewModel(savedStateHandle, mockRepository)

    viewModel.stateFlow.test {
        assertEquals(INITIAL_STATE, awaitItem())
        viewModel.trySendAction(ExampleAction.ButtonClick)
        assertEquals(INITIAL_STATE.copy(data = "data"), awaitItem())
    }

    coVerify { mockRepository.fetchData(any()) }
}

}

For complete examples: See references/test-base-classes.md

StateFlow vs EventFlow (Critical Distinction)

Flow Type Replay First Action Pattern

StateFlow Yes (1) awaitItem() gets current state Expect initial → trigger → expect new

EventFlow No expectNoEvents() first expectNoEvents → trigger → expect event

For detailed patterns: See references/flow-testing-patterns.md

B. Compose UI Testing Patterns

Base Class: BitwardenComposeTest

Always extend BitwardenComposeTest for Compose screen tests.

Location: app/src/test/kotlin/com/x8bit/bitwarden/ui/platform/base/BitwardenComposeTest.kt

Benefits:

• Pre-configures all Bitwarden managers (FeatureFlags, AuthTab, Biometrics, etc.)

• Wraps content in BitwardenTheme and LocalManagerProvider

• Provides fixed Clock for deterministic time-based tests

Pattern:

class ExampleScreenTest : BitwardenComposeTest() { private var haveCalledNavigateBack = false private val mutableEventFlow = bufferedMutableSharedFlow<ExampleEvent>() private val mutableStateFlow = MutableStateFlow(DEFAULT_STATE) private val viewModel = mockk<ExampleViewModel>(relaxed = true) { every { eventFlow } returns mutableEventFlow every { stateFlow } returns mutableStateFlow }

@Before
fun setup() {
    setContent {
        ExampleScreen(
            onNavigateBack = { haveCalledNavigateBack = true },
            viewModel = viewModel,
        )
    }
}

@Test
fun `on back click should send BackClick action`() {
    composeTestRule.onNodeWithContentDescription("Back").performClick()
    verify { viewModel.trySendAction(ExampleAction.BackClick) }
}

}

Note: Use bufferedMutableSharedFlow for event testing in Compose tests. Default replay is 0; pass replay = 1 if needed.

For complete base class details: See references/test-base-classes.md

C. Repository and Service Testing

Service Testing with MockWebServer

Base Class: BaseServiceTest (network/src/testFixtures/ )

class ExampleServiceTest : BaseServiceTest() { private val api: ExampleApi = retrofit.create() private val service = ExampleServiceImpl(api)

@Test
fun `getConfig should return success when API succeeds`() = runTest {
    server.enqueue(MockResponse().setBody(EXPECTED_JSON))
    val result = service.getConfig()
    assertEquals(EXPECTED_RESPONSE.asSuccess(), result)
}

}

Repository Testing Pattern

class ExampleRepositoryTest { private val fixedClock: Clock = Clock.fixed( Instant.parse("2023-10-27T12:00:00Z"), ZoneOffset.UTC, ) private val dispatcherManager = FakeDispatcherManager() private val mockDiskSource: ExampleDiskSource = mockk() private val mockService: ExampleService = mockk()

private val repository = ExampleRepositoryImpl(
    clock = fixedClock,
    exampleDiskSource = mockDiskSource,
    exampleService = mockService,
    dispatcherManager = dispatcherManager,
)

@Test
fun `fetchData should return success when service succeeds`() = runTest {
    coEvery { mockService.getData(any()) } returns expectedData.asSuccess()
    val result = repository.fetchData(userId)
    assertTrue(result.isSuccess)
}

}

Key patterns: Use FakeDispatcherManager , fixed Clock, and .asSuccess() helpers.

D. Test Data Builders

Builder Pattern with Number Parameter

Location: network/src/testFixtures/kotlin/com/bitwarden/network/model/

fun createMockCipher( number: Int, id: String = "mockId-$number", name: String? = "mockName-$number", // ... more parameters with defaults ): SyncResponseJson.Cipher

// Usage: val cipher1 = createMockCipher(number = 1) // mockId-1, mockName-1 val cipher2 = createMockCipher(number = 2) // mockId-2, mockName-2 val custom = createMockCipher(number = 3, name = "Custom")

Available Builders (35+):

• Cipher: createMockCipher() , createMockLogin() , createMockCard() , createMockIdentity() , createMockSecureNote() , createMockSshKey() , createMockField() , createMockUri() , createMockFido2Credential() , createMockPasswordHistory() , createMockCipherPermissions()

• Sync: createMockSyncResponse() , createMockFolder() , createMockCollection() , createMockPolicy() , createMockDomains()

• Send: createMockSend() , createMockFile() , createMockText() , createMockSendJsonRequest()

• Profile: createMockProfile() , createMockOrganization() , createMockProvider() , createMockPermissions()

• Attachments: createMockAttachment() , createMockAttachmentJsonRequest() , createMockAttachmentResponse()

See network/src/testFixtures/kotlin/com/bitwarden/network/model/ for full list.

E. Result Type Testing

Locations:

• .asSuccess() , .asFailure() : core/src/main/kotlin/com/bitwarden/core/data/util/ResultExtensions.kt

• assertCoroutineThrows : core/src/testFixtures/kotlin/com/bitwarden/core/data/util/TestHelpers.kt

// Create results "data".asSuccess() // Result.success("data") throwable.asFailure() // Result.failure<T>(throwable)

// Assertions assertTrue(result.isSuccess) assertEquals(expectedValue, result.getOrNull())

F. Test Utilities and Helpers

Fake Implementations

Fake Location Purpose

FakeDispatcherManager

core/src/testFixtures/

Deterministic coroutine execution

FakeConfigDiskSource

data/src/testFixtures/

In-memory config storage

FakeSharedPreferences

data/src/testFixtures/

Memory-backed SharedPreferences

Exception Testing (CRITICAL)

// CORRECT - Call directly, NOT inside runTest @Test fun test exception() { assertCoroutineThrows<IllegalStateException> { repository.throwingFunction() } }

Why: runTest catches exceptions and rethrows them, breaking the assertion pattern.

G. Critical Gotchas

Common testing mistakes in Bitwarden. For complete details and examples: See references/critical-gotchas.md

Core Patterns:

• assertCoroutineThrows + runTest - Never wrap in runTest ; call directly

• Static mock cleanup - Always unmockkStatic() in @After

• StateFlow vs EventFlow - StateFlow: awaitItem() first; EventFlow: expectNoEvents() first

• FakeDispatcherManager - Always use instead of real DispatcherManagerImpl

• Coroutine test wrapper - Use runTest { } for all Flow/coroutine tests

Assertion Patterns:

• Complete state assertions - Assert entire state objects, not individual fields

• JUnit over Kotlin - Use assertTrue() , not Kotlin's assert()

• Use Result extensions - Use asSuccess() and asFailure() for Result type assertions

Test Design:

• Fake vs Mock strategy - Use Fakes for happy paths, Mocks for error paths

• DI over static mocking - Extract interfaces (like UuidManager) instead of mockkStatic

• Null stream testing - Test null returns from ContentResolver operations

• bufferedMutableSharedFlow - Use with .onSubscription { emit(state) } in Fakes

• Test factory methods - Accept domain state types, not SavedStateHandle

H. Test File Organization

Directory Structure

module/src/test/kotlin/com/bitwarden/.../ ├── ui/*ScreenTest.kt, *ViewModelTest.kt ├── data/repository/*RepositoryTest.kt └── network/service/*ServiceTest.kt

module/src/testFixtures/kotlin/com/bitwarden/.../ ├── util/TestHelpers.kt ├── base/Base*Test.kt └── model/*Util.kt

Test Naming

• Classes: *Test.kt , *ScreenTest.kt , *ViewModelTest.kt

• Functions: given state when action should result

Summary

Key Bitwarden-specific testing patterns:

• BaseViewModelTest - Automatic dispatcher setup with stateEventFlow() helper

• BitwardenComposeTest - Pre-configured with all managers and theme

• BaseServiceTest - MockWebServer setup for network testing

• Turbine Flow Testing - StateFlow (replay) vs EventFlow (no replay)

• Test Data Builders - Consistent number: Int parameter pattern

• Fake Implementations - FakeDispatcherManager, FakeConfigDiskSource

• Result Type Testing - .asSuccess() , .asFailure()

Always consult: docs/ARCHITECTURE.md and existing test files for reference implementations.

Reference Documentation

For detailed information, see:

• references/test-base-classes.md

• Detailed base class documentation and usage patterns

• references/flow-testing-patterns.md

• Complete Turbine patterns for StateFlow/EventFlow

• references/critical-gotchas.md

• Full anti-pattern reference and debugging tips

Complete Examples:

• examples/viewmodel-test-example.md

• Full ViewModel test with StateFlow/EventFlow

• examples/compose-screen-test-example.md

• Full Compose screen test

• examples/repository-test-example.md

• Full repository test with mocks and fakes