Update testing docs

marcprux · marcprux · commit c58a5185fcb5 · 2026-03-13T13:52:19.000-04:00
diff --git a/src/content/docs/docs/modules/skip-sql/index.md b/src/content/docs/docs/modules/skip-sql/index.md
@@ -94,27 +94,59 @@ try sqlite.transaction {
 
 ### Schema Migration
 
-There is no built-in support for schema migrations. Following is a part of a sample of how you might perform migrations in your own app.
+SkipSQL provides built-in support for version-based schema migrations using SQLite's `userVersion` pragma. The `migrate()` method accepts an array of migration closures, each representing a schema version. Only migrations that haven't been applied yet will run, each within its own transaction:
+
+```swift
+try ctx.migrate(migrations: [
+    // Version 1: initial schema
+    { ctx in
+        try ctx.exec(sql: "CREATE TABLE DATA_ITEM (ID INTEGER PRIMARY KEY AUTOINCREMENT)")
+    },
+    // Version 2: add description column
+    { ctx in
+        try ctx.exec(sql: "ALTER TABLE DATA_ITEM ADD COLUMN DESCRIPTION TEXT")
+    },
+    // Version 3: add a new table
+    { ctx in
+        try ctx.createTableIfNotExists(NewTable.self)
+    },
+])
+```
+
+Each migration runs in a transaction and increments `userVersion` upon success. If a migration fails, it rolls back without affecting subsequent migrations. You can safely add new closures to the end of the array as your schema evolves — previously applied migrations are skipped.
+
+#### Helper Methods
+
+Additional schema utilities are available:
+
+```swift
+// Check if a table exists in the database
+let exists = try ctx.tableExists("DATA_ITEM") // true
+
+// Create a table from an SQLCodable type (safe if already exists)
+try ctx.createTableIfNotExists(DemoTable.self)
+
+// Add a column to an existing table (safe if already exists)
+try ctx.addColumnIfNotExists(DemoTable.newColumn, to: DemoTable.table)
+```
+
+#### Manual Migration
+
+For more control, you can implement migrations manually using the `userVersion` pragma directly:
 
 ```swift
-// track the version of the schema with the `userVersion` pragma, which can be used for schema migration
 func migrateSchema(v version: Int64, ddl: String) throws {
     if ctx.userVersion < version {
-        let startTime = Date.now
         try ctx.transaction {
-            try ctx.exec(sql: ddl) // perform the DDL operation
-            // then update the schema version
+            try ctx.exec(sql: ddl)
             ctx.userVersion = version
         }
-        logger.log("updated database schema to \(version) in \(startTime.durationToNow)")
     }
 }
 
-// the initial creation script for a new database
 try migrateSchema(v: 1, ddl: """
 CREATE TABLE DATA_ITEM (ID INTEGER PRIMARY KEY AUTOINCREMENT)
 """)
-// migrate records to have new description column
 try migrateSchema(v: 2, ddl: """
 ALTER TABLE DATA_ITEM ADD COLUMN DESCRIPTION TEXT
 """)
@@ -225,6 +257,73 @@ while let row = cursor.next() {
 }
 ```
 
+### Convenience Query Methods
+
+`SQLContext` provides several convenience methods for common operations on `SQLCodable` types:
+
+#### Checking Existence
+
+```swift
+// Check if any rows exist
+let hasRows = try ctx.exists(DemoTable.self)
+
+// Check if rows match a predicate
+let hasMatch = try ctx.exists(DemoTable.self, where: DemoTable.txt.equals(SQLValue("ABC")))
+```
+
+#### Fetching
+
+```swift
+// Fetch all rows
+let all: [DemoTable] = try ctx.fetchAll(DemoTable.self)
+
+// Fetch with filtering, ordering, and pagination
+let page: [DemoTable] = try ctx.fetchAll(DemoTable.self,
+    where: DemoTable.num.isNotNull(),
+    orderBy: DemoTable.int,
+    order: .descending,
+    limit: 10,
+    offset: 20)
+```
+
+#### Batch Insert
+
+```swift
+// Insert multiple instances in a single transaction
+let items = [
+    DemoTable(int: 1, txt: "A"),
+    DemoTable(int: 2, txt: "B"),
+    DemoTable(int: 3, txt: "C"),
+]
+let inserted = try ctx.insertAll(items) // returns instances with assigned primary keys
+```
+
+#### Deleting All Rows
+
+```swift
+// Delete all rows from a table
+try ctx.deleteAll(DemoTable.self)
+```
+
+#### Aggregate Functions
+
+```swift
+// Sum, average, min, max of a column
+let total = try ctx.sum(column: DemoTable.int, of: DemoTable.self)
+let average = try ctx.avg(column: DemoTable.int, of: DemoTable.self)
+let minimum = try ctx.min(column: DemoTable.int, of: DemoTable.self)
+let maximum = try ctx.max(column: DemoTable.int, of: DemoTable.self)
+
+// With filtering
+let filteredSum = try ctx.sum(column: DemoTable.int, of: DemoTable.self,
+    where: DemoTable.txt.isNotNull())
+
+// Generic aggregate for any SQL aggregate function
+let result = try ctx.aggregate("GROUP_CONCAT", column: DemoTable.txt, type: DemoTable.self)
+```
+
+All aggregate functions return an `SQLValue`, which can be accessed with `.longValue`, `.realValue`, `.textValue`, etc.
+
 ### Primary keys and auto-increment columns
 
 SkipSQL supports primary keys that work with SQLite's ROWID mechanism,
diff --git a/src/content/docs/docs/modules/skip-unit/index.md b/src/content/docs/docs/modules/skip-unit/index.md
@@ -58,7 +58,11 @@ By default, Skip uses the simulated Robolectric Android environment to run your
 
 ## Writing Tests
 
-A standard Skip test is just a plain XCTest:
+Skip Lite supports both XCTest and a subset of Swift Testing for writing transpiled tests.
+
+### XCTest
+
+A standard Skip test using XCTest:
 
 ```swift
 import XCTest
@@ -70,16 +74,51 @@ final class MyUnitTests: XCTestCase {
 }
 ```
 
+### Swift Testing
+
+You can also write tests using Swift Testing's `@Test` and `@Suite` annotations. The `#expect` macro maps to assertion functions and `#require` maps to `requireNotNil`:
+
+```swift
+import Testing
+
+@Suite struct MathTests {
+    @Test func addition() {
+        #expect(1 + 1 == 2)
+    }
+
+    @Test func inequality() {
+        #expect(3 != 5)
+    }
+}
+```
+
+Freestanding `@Test` functions (not inside a struct or class) are also supported and are automatically wrapped in a generated test class for JUnit:
+
+```swift
+import Testing
+
+@Test func addition() {
+    #expect(1 + 2 == 3)
+}
+```
+
+The following Swift Testing features are supported:
+- `@Test` functions (both as members and freestanding)
+- `@Suite` types
+- `#expect` with equality (`==`), inequality (`!=`), comparisons (`>`, `<`, `>=`, `<=`), and boolean expressions
+- `#require` for optional unwrapping
+
+Not all Swift Testing features are currently transpiled. Parameterized tests, traits, and tags are not supported.
+
 **Note**: The Skip transpiler currently does not have access to the internal API of the module being tested. If you take advantage of Swift's `@testable imports` to exercise internal API, the transpiler will not be able to perform its usual type inference when translating your test code. This just means that you might have to be more explicit about types and to fully-qualify values (e.g. `MyType.value` instead of just `.value`) when unit testing internal API.
 
 ## Running Tests
 
 The transpiled unit tests are intended to be run as part of the standard Xcode and Swift Package Manager testing process.
 
-This is done by adding one additional test class to the project's `Tests/ModuleNameTests/` folder named `XCSkipTests.swift`.
+The tests are driven by a test harness file called `XCSkipTests.swift`. If your test target does not already contain a file with this name, the Skip build plugin will auto-generate one during the build. This means that for most projects, you do not need to create or maintain this file yourself — just run `swift test` and the harness is created for you.
 
-This additional test class is added automatically when a library is created with the `skip init` command. 
-When adopting Skip into an existing process, add the test case manually:
+If you need to customize the test harness (for example, to specify a device target or adjust the Gradle task), you can add your own `XCSkipTests.swift` to your test target and the build plugin will use it instead of generating one:
 
 ```
 #if os(macOS) // Skip transpiled tests only run on macOS targets
@@ -90,14 +129,14 @@ import SkipTest
 final class XCSkipTests: XCTestCase, XCGradleHarness {
     public func testSkipModule() async throws {
         try await runGradleTests(device: .none) // set device ID to run in Android emulator vs. Robolectric
-    }   
-}       
+    }
+}
 #endif
 ```
 
 ### Running Tests from Xcode
 
-Once the `XCSkipTests.swift` file has been added to a project, the transpiled test cases will automatically run whenever testing against the **macOS** run destination.
+The transpiled test cases will automatically run whenever testing against the **macOS** run destination.
 As such, you need to ensure that your Swift code compiles and runs the same on macOS and iOS.
 This is a pre-requisite for Skip's parity testing, which runs the XCUnit test cases on macOS against the transpiled Kotlin tests in the Android testing environment. While many of the Foundation and SwiftUI APIs are identical on macOS and iOS, you may occasionally have to work around minor differences. 
 
diff --git a/src/content/docs/docs/modules/skip-web/index.md b/src/content/docs/docs/modules/skip-web/index.md
@@ -24,7 +24,7 @@ SkipWeb provides two ways to display web content in Skip Lite apps:
 | **Browser chrome** | Provided by the OS (address bar, back/forward, share) | You build your own toolbar and controls |
 | **JavaScript access** | None — the page runs in a sandboxed browser | Full `evaluateJavaScript` support |
 | **Navigation control** | None — the user navigates freely within the browser | Programmatic back/forward, reload, URL changes |
-| **Cookie/session sharing** | Shares the user's browser cookies and autofill | Isolated web engine per `WebView` instance |
+| **Cookie/session sharing** | Shares the user's browser cookies and autofill | Uses the app's WebView cookie store (shared across WebViews by default; not the same store as Safari/Chrome) |
 | **Customization** | Custom share-sheet actions | Full layout control, scroll delegates, snapshot API |
 
 Use `openWebBrowser` when you want to send the user to a web page with minimal code and maximum platform-native UX. Use `WebView` when you need to embed web content as part of your app's UI with programmatic control.
@@ -488,6 +488,58 @@ extension View {
 }
 ```
 
+## Cookies, Storage, and Cache
+
+`SkipWeb` exposes portable browser-data APIs through `WebEngine` and `WebViewNavigator`:
+
+- `cookies(for:)`
+- `cookieHeader(for:)`
+- `setCookie(_:requestURL:)`
+- `applySetCookieHeaders(_:for:)`
+- `clearCookies()`
+- `removeData(ofTypes:modifiedSince:)`
+
+Supporting types:
+
+- `WebCookie` (`name`, `value`, optional `domain`/`path`/`expires`, plus `isSecure`/`isHTTPOnly`)
+- `WebSiteDataType` (`cookies`, `diskCache`, `memoryCache`, `offlineWebApplicationCache`, `localStorage`, `sessionStorage`, `webSQLDatabases`, `indexedDBDatabases`)
+
+Example:
+
+```swift
+let url = URL(string: "https://example.com/path")!
+
+try await navigator.setCookie(
+    WebCookie(name: "session", value: "abc123"),
+    requestURL: url
+)
+
+let header = await navigator.cookieHeader(for: url)
+try await navigator.applySetCookieHeaders(
+    ["pref=1; Path=/; HttpOnly"],
+    for: url
+)
+await navigator.clearCookies()
+try await navigator.removeData(
+    ofTypes: Set([.diskCache, .memoryCache, .localStorage]),
+    modifiedSince: .distantPast
+)
+```
+
+Platform behavior:
+
+- iOS uses the web view's `websiteDataStore.httpCookieStore`.
+- On iOS, cookie scope follows the `WKWebsiteDataStore` attached to that `WKWebView`.
+- In default SkipWeb usage, that is WebKit's shared default data store, so cookies are shared across SkipWeb web views in the app.
+- On iOS, a custom `WKWebView` with a different data store (for example `WKWebsiteDataStore.nonPersistent()`) uses that store instead.
+- Android uses `android.webkit.CookieManager`.
+- On Android, `CookieManager` is a process-wide singleton store shared by all `WebView` instances (not per-`WebView` configurable).
+- `cookies(for:)` returns URL-matching cookies; on Android this is best-effort because `CookieManager` reads as a cookie-header string (limited metadata).
+- `setCookie(_:requestURL:)` requires either `cookie.domain` or a `requestURL` host; otherwise it throws `WebCookieError.missingCookieDomain`.
+- `removeData(ofTypes:modifiedSince:)` maps to iOS `WKWebsiteDataStore.removeData`.
+- On Android, `removeData` requires `modifiedSince == .distantPast` when `ofTypes` is non-empty; otherwise it throws `WebDataRemovalError.unsupportedModifiedSinceOnAndroid`.
+- Android data removal is bucket-level (cookies/cache/storage), not timestamp-granular, and may clear a broader bucket than an individual requested data type.
+
 ## Contribution
 
 Many delegates that are provided by `WKWebView` are not yet implemented in this project,
diff --git a/src/content/docs/docs/testing.md b/src/content/docs/docs/testing.md
@@ -15,7 +15,9 @@ Skip provides several ways to test your code on Android, depending on whether yo
 
 Skip Lite transpiles your Swift source into Kotlin, and your XCTest test cases into JUnit tests. This means your tests run as standard JUnit on the Android side, which plugs into the well-established Gradle testing infrastructure.
 
-When you create a Skip Lite package with `skip init`, an `XCSkipTests.swift` file is automatically added to your test target:
+The transpiled tests are driven by a test harness file called `XCSkipTests.swift`. If your test target does not already contain a file with this name, the Skip build plugin will auto-generate one during the build. This means that for most projects, you do not need to create or maintain this file yourself — just run `swift test` and the harness is created for you.
+
+If you need to customize the test harness (for example, to specify a device target or adjust the Gradle task), you can add your own `XCSkipTests.swift` to your test target and the build plugin will use it instead of generating one. A typical custom harness looks like this:
 
 ```swift
 #if os(macOS) // Skip transpiled tests only run on macOS targets
@@ -32,7 +34,10 @@ final class XCSkipTests: XCTestCase, XCGradleHarness {
 
 This test harness is what connects Xcode to the Gradle test pipeline. When you run tests against the **macOS** destination in Xcode (or via `swift test` on the command line), `testSkipModule()` triggers the full transpilation and Gradle build, runs the JUnit tests, and reports the results back as XCTest outcomes. The net effect is that you get parity testing across both platforms from a single test run.
 
-The limitation is that only XCTest-style tests are supported. Your Swift tests are transpiled into Kotlin JUnit, so they are subject to the same transpilation constraints as the rest of your Skip Lite code. Swift Testing (`@Test`) is not available in this mode.
+Your Swift tests are transpiled into Kotlin JUnit, so they are subject to the same transpilation constraints as the rest of your Skip Lite code. Both XCTest and a subset of Swift Testing are supported:
+
+- **XCTest**: Classes inheriting from `XCTestCase` with `test`-prefixed methods are transpiled into JUnit test classes with `@Test` annotations. Standard `XCTAssert*` functions map to JUnit assertions.
+- **Swift Testing**: Functions annotated with `@Test` and types annotated with `@Suite` are also transpiled into JUnit tests. The `#expect` macro is mapped to assertion functions (`expectEqual`, `expectNotEqual`, `expectTrue`, `expectGreaterThan`, etc.) and `#require` is mapped to `requireNotNil`. Freestanding `@Test` functions (not inside a struct or class) are automatically wrapped in a generated test class. Not all Swift Testing features are supported — parameterized tests, traits, and tags are not currently transpiled.
 
 ### Local Testing with Robolectric
 
@@ -110,7 +115,7 @@ func testAndroidSpecificFeature() {
 | | Skip Lite (Robolectric) | Skip Lite (Instrumented) | Skip Fuse (CLI) | Skip Fuse (APK) |
 |---|---|---|---|---|
 | **Command** | `swift test` | `ANDROID_SERIAL=… swift test` | `skip android test` | `skip android test --apk` |
-| **Test framework** | XCTest only (transpiled to JUnit) | XCTest only (transpiled to JUnit) | XCTest + Swift Testing | Swift Testing only |
+| **Test framework** | XCTest + Swift Testing (transpiled to JUnit) | XCTest + Swift Testing (transpiled to JUnit) | XCTest + Swift Testing | Swift Testing only |
 | **Runs on** | Host JVM (macOS/Linux) | Android emulator/device | Android emulator/device via `adb shell` | Android emulator/device as installed APK |
 | **Android APIs** | Simulated via Robolectric | Full | Not available (no JVM/JNI) | Full (real app process with JNI) |
 | **Resource bundles** | Managed by Gradle | Managed by Gradle | Yes (sidecar `.resources` dirs) | No (no Foundation APK bundle support) |
