feat: Improve wasmJs and iOS testing and database handling

- Refactor WebAssembly (wasmJs) database worker to support both SQLite3-WASM/OPFS and SQL.js as a fallback.
- Add `deleteDatabase` functionality for iOS to properly clean up database files, including WAL and SHM.
- Configure wasmJs browser tests to run with Karma and Chrome.
- Introduce `WebUiTests.kt` and `IosUiTests.kt` extending a common test base to improve test isolation.
- Bump app versions to `8.5.0` for Android and iOS.

refactor: Use test tags and remove `runBlockingAll` in UI tests

- Replace string resource lookups in UI tests with `testTag` modifiers for improved stability and performance.
- Create a centralized `TestTags.kt` file to define all UI test tags.
- Remove the `runBlockingAll` utility and update tests to use standard coroutine scopes.
- Add a reusable `PasswordSaveButton` composable to reduce code duplication in password-related dialogs.

docs: Consolidate documentation into the /docs directory

- Move module structure, version management, and testing documentation into the central `/docs` directory.
- Update `CONTRIBUTING.md` and other guides to link to the new centralized documentation.

Author: softartdev

AGENTS.md

@@ -21,7 +21,9 @@
 - Desktop app: `./gradlew :app:desktop:run` (launches JVM desktop Compose app).
 - Desktop UI tests: `./gradlew :app:desktop:jvmTest` (uses `uiTestJUnit4`).
 - iOS: `cd iosApp && pod install` then open `iosApp/iosApp.xcworkspace` in Xcode and run. Regenerate podspec if needed: `./gradlew :app:ios-kit:podspec`.
+- iOS UI tests: `./gradlew :app:ios-kit:iosSimulatorArm64Test` (requires iOS simulator; uses multiplatform Compose UI tests).
 - Web app: `./gradlew :app:web:wasmJsBrowserDevelopmentRun --continuous` (launches the web app in a browser with hot reload).
+- Web UI tests: `./gradlew :app:web:wasmJsBrowserTest` (requires Chrome binary via `CHROME_BIN` environment variable; uses Karma/Chrome headless).
 - Build without iOS link tasks: `./gradle/build_quick.sh` (see [gradle/build_quick.sh](gradle/build_quick.sh))
 
 ## AI Agent Workflow for Verifying Changes
@@ -40,6 +42,8 @@ After making changes, AI agents must perform the following checks sequentially.
 - Unit tests: Kotlin Multiplatform `kotlin("test")`/JUnit. Run all with `./gradlew test` or per module (e.g., `:ui:shared:jvmTest`).
 - Android UI tests: Espresso/Compose in `app/android/src/androidTest`. Run with `connectedCheck`.
 - Desktop UI tests: in `app/desktop/src/jvmTest` using `uiTestJUnit4`.
+- iOS UI tests: Multiplatform Compose UI tests in `app/ios-kit/src/commonTest`. Run with `:app:ios-kit:iosSimulatorArm64Test`.
+- Web UI tests: Multiplatform Compose UI tests in `app/web/src/wasmJsTest`. Run with `:app:web:wasmJsBrowserTest` (requires `CHROME_BIN` environment variable).
 - Name tests `FooBarTest.kt`; prefer Given_When_Then method names.
 
 ## Commit & Pull Request Guidelines

CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.5.0] - 2026-01-08
+
+### Features
+- Improve wasmJs and iOS database handling and tests
+  - Refactor WebAssembly (wasmJs) database worker to support both SQLite3-WASM/OPFS and SQL.js as a fallback
+  - Add `deleteDatabase` functionality for iOS to properly clean up database files (WAL and SHM)
+  - Configure wasmJs browser tests to run with Karma and Chrome
+  - Improve test isolation across platforms
+
+### Bug Fixes
+- Fix build warnings related to Kotlin compiler options and wasmJs API changes
+  - Add `-Xexpect-actual-classes` compiler option to support new class hierarchy model
+  - Update `runBlockingAll` implementation for wasmJs target to use `startCoroutine`
+  - Fix webpack configuration for dynamic repo root detection and SQLite WASM asset availability
+
+### Refactoring
+- Improve database connection handling and error checking
+  - Refactor `checkDbConnection` into `hasDbConnection` suspend function in MainViewModel
+  - Introduce safer access patterns with proper exception handling
+  - Use more specific exception types (e.g., `java.sql.SQLException`)
+- Consolidate documentation into `/docs` directory
+  - Move module structure and version management documentation
+  - Update contributing guides to link to centralized documentation
+- Use test tags instead of string resources in UI tests
+  - Create centralized `TestTags.kt` for all test tag constants
+  - Update UI composables to use `modifier.testTag()` attribute
+  - Improve test stability by removing dynamic string lookups
+  - Create reusable `PasswordSaveButton` composable to eliminate duplication
+- Remove `runBlockingAll` from UI tests
+  - Simplify UI test code by using coroutine scopes directly
+  - Update `DbTestEncryptor` to be a suspend function
+  - Align test infrastructure with modern Kotlin coroutines patterns
+
+### Chores
+- Format `build.gradle.kts` for Android
+- Update dependencies and optimization settings
+- Improve code organization and consistency
+
 ## [8.4.9] - 2025-12-23
 
 ### Features

CONTRIBUTING.md

@@ -341,31 +341,7 @@ class FeatureViewModelTest {
 
 ## Module Structure
 
-### Core Modules
-
-- **core:domain** - Pure business logic, no dependencies
-- **core:presentation** - ViewModels, state management
-- **core:data:db-sqldelight** - SQLDelight data implementation (default)
-- **core:data:db-room** - Room data implementation (alternative)
-- **core:test** - Shared test utilities
-
-### UI Modules
-
-- **ui:shared** - Shared Compose UI (100% shared)
-- **ui:test-jvm** - UI testing framework (Kaspresso-inspired)
-
-### App Modules
-
-- **app:android** - Android application
-- **app:desktop** - Desktop JVM application
-- **app:web** - Web/Wasm application
-- **app:ios-kit** - iOS framework (CocoaPods)
-- **app:iosApp** - iOS application (Swift/SwiftUI)
-
-### Build Modules
-
-- **build-logic** - Gradle convention plugins
-- **thirdparty** - Vendored dependencies
+**See [docs/README.md](docs/README.md#module-documentation) for the list of modules and their documentation.**
 
 ### Module Guidelines
 

app/android/build.gradle.kts

@@ -24,8 +24,8 @@ android {
         applicationId = "com.softartdev.noteroom"
         minSdk = libs.versions.minSdk.get().toInt()
         targetSdk = libs.versions.targetSdk.get().toInt()
-        versionCode = 849
-        versionName = "8.4.9"
+        versionCode = 850
+        versionName = "8.5.0"
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
         testInstrumentationRunnerArguments["clearPackageData"] = "true"
         vectorDrawables.useSupportLibrary = true
@@ -40,7 +40,10 @@ android {
         getByName("release") {
             isMinifyEnabled = true
             isShrinkResources = true
-            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
             configure<CrashlyticsExtension> { mappingFileUploadEnabled = true }
             signingConfig = signingConfigs.getByName("config")
         }
@@ -58,7 +61,7 @@ android {
         compose = true
     }
     packagingOptions.resources.excludes.add("/META-INF/{AL2.0,LGPL2.1}")
-    testOptions{
+    testOptions {
         execution = "ANDROIDX_TEST_ORCHESTRATOR"
         emulatorControl.enable = true
     }
@@ -112,6 +115,6 @@ dependencies {
     androidTestImplementation(libs.leakCanary.android.instrumentation)
     lintChecks(libs.android.security.lint)
 }
-tasks.withType<UploadMappingFileTask>{
+tasks.withType<UploadMappingFileTask> {
     dependsOn("processDebugGoogleServices")
 }

app/android/src/androidTest/java/com/softartdev/notedelight/ui/CustomActivityScenarioRule.kt

@@ -4,17 +4,18 @@ import android.app.Activity
 import androidx.activity.ComponentActivity
 import androidx.compose.ui.test.junit4.AndroidComposeTestRule
 import androidx.test.core.app.ActivityScenario
+import kotlinx.coroutines.runBlocking
 import org.junit.rules.ExternalResource
 
 inline fun <reified A : ComponentActivity> customAndroidComposeRule(
-    noinline beforeActivityLaunched: () -> Unit
+    noinline beforeActivityLaunched: suspend () -> Unit
 ): AndroidComposeTestRule<CustomActivityScenarioRule<A>, A> {
     return customAndroidComposeRule(A::class.java, beforeActivityLaunched)
 }
 
 fun <A : ComponentActivity> customAndroidComposeRule(
     activityClass: Class<A>,
-    beforeActivityLaunched: () -> Unit
+    beforeActivityLaunched: suspend () -> Unit
 ): AndroidComposeTestRule<CustomActivityScenarioRule<A>, A> = AndroidComposeTestRule(
     activityRule = CustomActivityScenarioRule(activityClass, beforeActivityLaunched),
     activityProvider = ::provideActivity
@@ -30,13 +31,13 @@ fun <A : Activity> provideActivity(customActivityScenarioRule: CustomActivitySce
 
 class CustomActivityScenarioRule<A : Activity>(
     private val activityClass: Class<A>,
-    private val beforeActivityLaunched: () -> Unit
+    private val beforeActivityLaunched: suspend () -> Unit
 ) : ExternalResource() {
 
     internal lateinit var scenario: ActivityScenario<A>
 
     override fun before() {
-        beforeActivityLaunched()
+        runBlocking { beforeActivityLaunched() }
         scenario = ActivityScenario.launch(activityClass)
     }
 

app/android/src/androidTest/java/com/softartdev/notedelight/ui/SignOutTest.kt

@@ -2,18 +2,16 @@ package com.softartdev.notedelight.ui
 
 import androidx.compose.ui.test.assertIsDisplayed
 import androidx.compose.ui.test.junit4.createAndroidComposeRule
-import androidx.compose.ui.test.onNodeWithContentDescription
+import androidx.compose.ui.test.onNodeWithTag
 import androidx.lifecycle.Lifecycle.State.DESTROYED
 import androidx.test.espresso.Espresso
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import androidx.test.filters.LargeTest
 import com.softartdev.notedelight.MainActivity
+import com.softartdev.notedelight.util.CREATE_NOTE_FAB_TAG
 import kotlinx.coroutines.test.runTest
 import leakcanary.DetectLeaksAfterTestSuccess
 import leakcanary.TestDescriptionHolder
-import notedelight.ui.shared.generated.resources.Res
-import notedelight.ui.shared.generated.resources.create_note
-import org.jetbrains.compose.resources.getString
 import org.junit.Assert.assertTrue
 import org.junit.Rule
 import org.junit.Test
@@ -34,7 +32,7 @@ class SignOutTest {
     @Test
     fun signOutTest() = runTest {
         composeTestRule
-            .onNodeWithContentDescription(label = getString(Res.string.create_note))
+            .onNodeWithTag(CREATE_NOTE_FAB_TAG)
             .assertIsDisplayed()
 
         Espresso.pressBackUnconditionally()

app/desktop/build.gradle.kts

@@ -16,9 +16,6 @@ kotlin {
     applyDefaultHierarchyTemplate()
 
     sourceSets {
-        all {
-            languageSettings.optIn("kotlin.RequiresOptIn")
-        }
         jvmMain.dependencies {
             implementation(projects.core.domain)
             implementation(projects.core.presentation)
@@ -44,6 +41,9 @@ kotlin {
             implementation(libs.kotlinx.datetime)
             implementation(libs.androidx.lifecycle.runtime.testing)
         }
+        all {
+            languageSettings.optIn("kotlin.RequiresOptIn")
+        }
     }
 }
 
@@ -53,7 +53,7 @@ compose.desktop {
         nativeDistributions {
             targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
             packageName = "Note Delight"
-            packageVersion = "8.4.9"
+            packageVersion = "8.5.0"
             description = "Note app with encryption"
             copyright = "© 2023 SoftArtDev"
             macOS.iconFile.set(project.file("src/jvmMain/resources/app_icon.icns"))

app/ios-kit/README.md

@@ -358,6 +358,44 @@ dependencies {
 
 Kotlin code can be debugged from Xcode with proper symbol mapping.
 
+## Testing
+
+### UI Tests
+
+The iOS kit includes multiplatform Compose UI tests that extend `CommonUiTests` from the `ui/test` module:
+
+**Location**: `app/ios-kit/src/commonTest/kotlin/IosUiTests.kt`
+
+**Test Coverage**:
+- CRUD operations
+- Title editing after create/save
+- Database prepopulation
+- Encryption flow
+- Password settings
+- Locale switching
+
+**Running Tests**:
+
+```bash
+# Requires iOS Simulator to be running
+./gradlew :app:ios-kit:iosSimulatorArm64Test
+```
+
+**Test Configuration**:
+- Tests run on iOS Simulator (arm64)
+- Uses Compose Multiplatform testing API
+- Database is automatically cleaned up before each test
+- Handles iOS-specific database file cleanup (WAL, journal files)
+
+**Database Management**:
+Tests use improved database deletion that properly handles:
+- Main database file (`notes.db`)
+- Write-Ahead Logging files (`notes.db-wal`)
+- Shared memory files (`notes.db-shm`)
+- Journal files (`notes.db-journal`)
+
+This ensures clean test state and prevents test interference.
+
 ## Updating Framework
 
 After changing Kotlin code:

app/ios-kit/build.gradle.kts

@@ -1,4 +1,7 @@
+@file:OptIn(ExperimentalComposeLibrary::class)
+
 import org.gradle.internal.os.OperatingSystem
+import org.jetbrains.compose.ExperimentalComposeLibrary
 
 plugins {
     alias(libs.plugins.kotlin.multiplatform)
@@ -39,5 +42,13 @@ kotlin {
             implementation(project.dependencies.platform(libs.koin.bom))
             api(libs.koin.core)
         }
+        commonTest.dependencies {
+            implementation(kotlin("test"))
+            implementation(projects.ui.test)
+            implementation(compose.uiTest)
+            implementation(compose.materialIconsExtended)
+            implementation(libs.androidx.lifecycle.runtime.compose)
+            implementation(libs.androidx.lifecycle.runtime.testing)
+        }
     }
 }

app/ios-kit/src/commonTest/kotlin/com/softartdev/notedelight/IosUiTests.kt

@@ -0,0 +1,36 @@
+package com.softartdev.notedelight
+
+import kotlinx.coroutines.test.TestResult
+import kotlin.test.AfterTest
+import kotlin.test.BeforeTest
+import kotlin.test.Test
+
+class IosUiTests : CommonUiTests() {
+
+    @BeforeTest
+    override fun setUp() = super.setUp()
+
+    @AfterTest
+    override fun tearDown() = super.tearDown()
+
+    @Test
+    override fun crudNoteTest(): TestResult = super.crudNoteTest()
+
+    @Test
+    override fun editTitleAfterCreateTest(): TestResult = super.editTitleAfterCreateTest()
+
+    @Test
+    override fun editTitleAfterSaveTest(): TestResult = super.editTitleAfterSaveTest()
+
+    @Test
+    override fun prepopulateDatabase(): TestResult = super.prepopulateDatabase()
+
+    @Test
+    override fun flowAfterCryptTest(): TestResult = super.flowAfterCryptTest()
+
+    @Test
+    override fun settingPasswordTest(): TestResult = super.settingPasswordTest()
+
+    @Test
+    override fun localeTest(): TestResult = super.localeTest()
+}