@guidelytech/flags 0.7.0 → 0.8.0

package/README.md

@@ -102,7 +102,8 @@ your fallback, and afterwards the last good payload.
 | `payload` / `remoteResults` | — | Bootstrap: used immediately (`ready` at once). |
 | `remoteEval` | `false` | Evaluate on the server (`POST /flags/evaluate`) for environments that hide their rules. Switched on automatically when a public key gets `remote_evaluation_required`. Re-evaluates (debounced) when attributes change; results are cached per attribute set. |
 | `decryptionKey` | — | For encrypted payloads (AES-256-GCM via WebCrypto). |
-| `overrides` / `overrideBehaviour` | — / `localOverRemote` | `localOnly` (never fetch), `localOverRemote` (overrides win), `remoteOverLocal` (only for flags missing remotely). |
+| `overrides` / `overrideBehaviour` | — / `localOverRemote` | `localOnly` (never fetch; overrides, then the bootstrap `payload`), `localOverRemote` (overrides win), `remoteOverLocal` (only for flags missing remotely). |
+| `devOverrides` | `true` | Read [dev overrides](#dev-overrides-ci-and-tests) from environment variables and test globals. |
 | `enableUrlOverrides` | `false` | Browser QA: `?guidely_flags=new-checkout:true,checkout-button-color:"green"`. |
 | `stickyBucketService` | — | `InMemoryStickyBucketStore` / `LocalStorageStickyBucketStore`: users keep their experiment variation. |
 | `storage` | `localStorage` in browsers | Any `getItem`/`setItem` store, sync or async (AsyncStorage). `false` disables. |
@@ -115,6 +116,52 @@ your fallback, and afterwards the last good payload.
 `createStaticFlags({ payload, attributes })` gives the same getters over a payload with no network
 or tracking — framework bindings use it to server-render and hydrate.
 
+## Dev overrides (CI and tests)
+
+Pin flag values without touching the app. Every client reads these once, when it is created:
+
+| Source | Example |
+|---|---|
+| `GUIDELY_FLAG_OVERRIDES` | `new-checkout:true,limit:5,theme:"dark"` or `{"new-checkout":true}` |
+| `GUIDELY_FLAG_OVERRIDES_FILE` | path to a file holding the same text (JSON object or one `key:value` per line) |
+| `GUIDELY_FLAG_OVERRIDE_BEHAVIOUR` | `localOnly` — no network, no cached payload: hermetic tests |
+| `globalThis.__GUIDELY_FLAG_OVERRIDES__` / `__GUIDELY_FLAG_OVERRIDE_BEHAVIOUR__` | an object or the same text, set by a test runner in the page |
+
+```bash
+GUIDELY_FLAG_OVERRIDES='new-checkout:true' GUIDELY_FLAG_OVERRIDE_BEHAVIOUR=localOnly pnpm test
+GUIDELY_FLAG_OVERRIDES_FILE=ci/flags.json pnpm test
+```
+
+A sample `ci/flags.json` (keys are flag keys; give each value the flag's type, since a value of the
+wrong type or `null` makes the getter return its fallback):
+
+```json
+{
+  "new-checkout": true,
+  "checkout-button-color": "green",
+  "max-cart-items": 25,
+  "pricing-page": { "layout": "grid", "plans": ["starter", "pro", "team"] },
+  "holiday-banner": null
+}
+```
+
+```ts
+// Playwright: set before the page's scripts run.
+await page.addInitScript(() => {
+  (window as any).__GUIDELY_FLAG_OVERRIDES__ = { "new-checkout": true };
+});
+// Cypress: cy.visit("/", { onBeforeLoad: (win) => { win.__GUIDELY_FLAG_OVERRIDES__ = { "new-checkout": true }; } });
+```
+
+Per flag, later wins: `overrides` / `setOverrides()` → file → variable → global → `?guidely_flags=`.
+`setOverrides()` only replaces the first. Values are served with reason `OVERRIDE`. The client
+logs one warning listing the sources in use, so a variable left set in production shows up in
+logs; malformed sources go to `onError` and are ignored. `devOverrides: false` turns it all off.
+
+With server rendering, set both: the variable for server code and the global for the browser
+(React and Svelte server renders read the bootstrap payload, which carries no overrides).
+`parseOverrides(text)` is exported for reading the same format elsewhere.
+
 ## CLI
 
 ```bash