Merge pull request #77 from EtaCassiopeia/docs/testkit-isolation

Update docs for isolated test API instances

Author: EtaCassiopeia

docs/architecture.md

@@ -116,7 +116,7 @@ FeatureFlags.fromProvider(provider)
 | Method | Description |
 |:-------|:------------|
 | `fromProvider(provider)` | Create from any OpenFeature provider |
-| `fromProviderWithDomain(provider, domain)` | Create with named domain for test isolation |
+| `fromProviderWithDomain(provider, domain)` | Create with named domain/client |
 | `fromProviderWithHooks(provider, hooks)` | Create with initial hooks |
 | `fromMultiProvider(providers)` | Combine multiple providers (first-match strategy) |
 | `fromMultiProvider(providers, strategy)` | Combine multiple providers with custom strategy |

docs/providers.md

@@ -279,15 +279,14 @@ val layer: ZLayer[Scope, Throwable, FeatureFlags] =
 
 ### fromProviderWithDomain
 
-Create with a named domain for test isolation. Each domain gets its own client:
+Create with a named domain. Each domain gets its own client, useful for segmenting feature flag configuration:
 
 ```scala
 val layer = FeatureFlags.fromProviderWithDomain(provider, "my-service")
-
-// Useful for testing - each test can use a different domain
-val testLayer = FeatureFlags.fromProviderWithDomain(testProvider, "test-domain-123")
 ```
 
+> For test isolation, prefer `TestFeatureProvider.layer` which automatically creates isolated API instances.
+
 ### fromProviderWithHooks
 
 Create with initial hooks:
@@ -567,12 +566,14 @@ val ctx = EvaluationContext(userId)
 FeatureFlags.boolean("feature", false, ctx)
 ```
 
-### 5. Use Domain Isolation in Tests
+### 5. Use Testkit Layers for Isolation
+
+`TestFeatureProvider.layer` creates an isolated API instance per test — no manual domain management needed:
 
 ```scala
-val testLayer = FeatureFlags.fromProviderWithDomain(
-  testProvider,
-  s"test-${java.util.UUID.randomUUID()}"
-)
+test("my test") {
+  for result <- FeatureFlags.boolean("flag", false)
+  yield assertTrue(result == true)
+}.provide(Scope.default >>> TestFeatureProvider.layer(Map("flag" -> true)))
 ```
 

docs/testkit.md

@@ -357,39 +357,40 @@ The `asyncLayer` creates a provider that starts in `NotReady` state. Call `setSt
 
 ## Test Isolation
 
-### Domain-Based Isolation
+### Automatic Isolation
 
-Use `FeatureFlags.fromProviderWithDomain` for test isolation when tests run in parallel:
+`TestFeatureProvider.layer`, `asyncLayer`, and `layerFrom` each create an **isolated `OpenFeatureAPI` instance** with its own provider repository and event support. This means tests using these layers can run in parallel without cross-test contamination — no extra configuration needed.
 
 ```scala
-test("isolated test 1") {
-  for
-    provider <- TestFeatureProvider.make(Map("flag" -> true))
-    layer     = TestFeatureProvider.layerFrom(provider)
-    result   <- FeatureFlags.boolean("flag", false).provide(Scope.default >>> layer)
+// These tests run in parallel safely — each gets its own isolated API instance
+test("test 1") {
+  for result <- FeatureFlags.boolean("flag", false)
   yield assertTrue(result == true)
-}
+}.provide(Scope.default >>> TestFeatureProvider.layer(Map("flag" -> true)))
 
-test("isolated test 2") {
-  for
-    provider <- TestFeatureProvider.make(Map("flag" -> false))
-    layer     = TestFeatureProvider.layerFrom(provider)
-    result   <- FeatureFlags.boolean("flag", false).provide(Scope.default >>> layer)
+test("test 2") {
+  for result <- FeatureFlags.boolean("flag", false)
   yield assertTrue(result == false)
-}
+}.provide(Scope.default >>> TestFeatureProvider.layer(Map("flag" -> false)))
 ```
 
-### Sequential Tests
-
-For tests that share state, run them sequentially:
+If you need to access both the provider and the `FeatureFlags` service (e.g. to track evaluations or emit events), use `layerFrom`:
 
 ```scala
-suite("shared state tests")(
-  test("test 1") { ... },
-  test("test 2") { ... }
-) @@ TestAspect.sequential
+test("tracks evaluations") {
+  for
+    provider <- TestFeatureProvider.make(Map("flag" -> true))
+    layer     = TestFeatureProvider.layerFrom(provider)
+    _        <- FeatureFlags.boolean("flag", false).provide(Scope.default >>> layer)
+    was      <- provider.wasEvaluated("flag")
+  yield assertTrue(was)
+}
 ```
 
+> **Note:** The public factory methods (`FeatureFlags.fromProvider`, `fromMultiProvider`, etc.)
+> use the global `OpenFeatureAPI` singleton and are **not** isolated. If you test with these
+> directly, use `@@ TestAspect.sequential` to prevent conflicts.
+
 ---
 
 ## Best Practices