feat(example): read QA config from dart-define instead of source patching (#168)

## Description

Refactors the example app so QA smoke tests can inject `qa_run_id`
session
attributes and a startup `FaroUser` via `api-config.json` dart-define
keys,
removing the need to temporarily patch `main.dart` source code.

Adds a `QaConfig` class that reads two optional keys at startup:
- `FARO_QA_RUN_ID` — included in `sessionAttributes` when non-empty
- `FARO_QA_INITIAL_USER_JSON` — parsed into a `FaroUser` for
`initialUser`

When absent or empty, the app behaves exactly as before.

## Type of Change

- [x] 🚀 New feature (non-breaking change which adds functionality)
- [x] 📝 Documentation

## Checklist

- [x] I have made corresponding changes to the documentation
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have updated the CHANGELOG.md under the "Unreleased" section

## Additional Notes

- All changes are scoped to `example/` (plus docs in `AGENTS.md`)
- No SDK (`lib/`) changes
- 13 new unit tests covering: empty/missing config, valid user JSON,
  invalid JSON graceful fallback, non-string attribute coercion,
  combined run ID + user
- CHANGELOG not updated since this is an example-app-only change — let
me
  know if you'd like an entry added

Made with [Cursor](https://cursor.com)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Changes are isolated to the `example/` app and documentation, with
defensive parsing and tests; no SDK or security-sensitive logic is
modified.
> 
> **Overview**
> Adds opt-in QA smoke-test overrides to the example app via
`--dart-define-from-file`, allowing tests to inject a `qa_run_id`
session attribute and an initial `FaroUser` from
`FARO_QA_INITIAL_USER_JSON` without editing source.
> 
> Introduces `QaConfig` (with unit tests) to parse and validate these
values (including graceful fallback on invalid JSON and attribute string
coercion), wires it into `example/lib/main.dart`, and documents the new
config keys in `AGENTS.md`, `example/README.md`, and
`api-config.example.json`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
cb7d785. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: robert-northmind

AGENTS.md

@@ -259,6 +259,22 @@ There is no Android emulator in this environment. To build the example APK:
 cd example && flutter build apk --dart-define-from-file api-config.json
 ```
 
+### QA smoke-test overrides
+
+The example app reads optional QA dart-define keys (`FARO_QA_RUN_ID`, `FARO_QA_INITIAL_USER_JSON`) from `api-config.json` to inject session attributes and an initial user without patching source code. Include them in the config file:
+
+```json
+{
+  "FARO_COLLECTOR_URL": "https://...",
+  "FARO_QA_RUN_ID": "smoke-123",
+  "FARO_QA_INITIAL_USER_JSON": "{\"id\":\"qa-user\",\"username\":\"bot\"}"
+}
+```
+
+Then run as usual: `flutter run --dart-define-from-file api-config.json`
+
+See `example/README.md` § "QA Smoke Test Configuration" for the full reference.
+
 ### Before opening a PR
 
 Run the pre-release check script before committing/opening a PR. It validates formatting, static analysis, tests, and CHANGELOG content in one step:

example/README.md

@@ -129,6 +129,43 @@ Key implementation features shown in this example:
    - Error boundary setup
    - ANR detection configuration
 
+## QA Smoke Test Configuration
+
+The example app supports optional QA dart-define keys that inject session
+attributes and an initial user at startup, removing the need to patch source
+code for automated smoke tests.
+
+| Key | Type | Purpose |
+|-----|------|---------|
+| `FARO_QA_RUN_ID` | string | Adds `qa_run_id` to session attributes |
+| `FARO_QA_INITIAL_USER_JSON` | stringified JSON | Sets the initial `FaroUser` |
+
+Both keys are optional. When absent or empty, the app behaves normally.
+
+All configuration lives in `api-config.json` and is passed via a single flag:
+
+```bash
+flutter run --dart-define-from-file api-config.json
+```
+
+### Example: api-config.json with QA fields
+
+```json
+{
+  "FARO_COLLECTOR_URL": "https://your-collector-url",
+  "FARO_QA_RUN_ID": "smoke-test-12345",
+  "FARO_QA_INITIAL_USER_JSON": "{\"id\":\"user-123\",\"username\":\"qa-bot\",\"email\":\"qa@test.com\",\"attributes\":{\"role\":\"tester\"}}"
+}
+```
+
+The user JSON value must be a stringified JSON object (escaped quotes).
+Automation agents can produce this by JSON-encoding the user map into a string
+value.
+
+Non-string attribute values (booleans, numbers) in the user JSON are
+automatically converted to strings to match the `FaroUser.attributes` contract.
+Invalid JSON is silently ignored, falling back to the normal initial user.
+
 ## Testing Features
 
 The app provides interactive buttons to test various SDK features:

example/api-config.example.json

@@ -1,4 +1,12 @@
 {
   "_comment": "Grafana Cloud: Get URL from Frontend Observability > Your App > Web SDK Config. Self-hosted: Use your Grafana Alloy faro.receiver endpoint.",
-  "FARO_COLLECTOR_URL": "https://faro-collector-prod-us-central-0.grafana.net/collect/YOUR_API_KEY"
+  "FARO_COLLECTOR_URL": "https://faro-collector-prod-us-central-0.grafana.net/collect/YOUR_API_KEY",
+
+  "_qa_comment": "Optional QA fields below. Omit or leave empty for normal app behavior. The user JSON value must be a stringified JSON object (escaped quotes).",
+  "FARO_QA_RUN_ID": "",
+  "FARO_QA_INITIAL_USER_JSON": "",
+
+  "_qa_example_comment": "Example with QA values populated:",
+  "_qa_example_FARO_QA_RUN_ID": "smoke-test-12345",
+  "_qa_example_FARO_QA_INITIAL_USER_JSON": "{\"id\":\"user-123\",\"username\":\"qa-bot\",\"email\":\"qa@test.com\",\"attributes\":{\"role\":\"tester\"}}"
 }

example/lib/main.dart

@@ -4,16 +4,17 @@ import 'package:faro/faro.dart';
 import 'package:faro_example/features/app_diagnostics/presentation/app_diagnostics_page.dart';
 import 'package:faro_example/features/custom_telemetry/presentation/custom_telemetry_page.dart';
 import 'package:faro_example/features/feature_catalog/presentation/feature_catalog_page.dart';
+import 'package:faro_example/features/network_requests/presentation/network_requests_page.dart';
 import 'package:faro_example/features/sampling_settings/domain/sampling_settings_service.dart';
 import 'package:faro_example/features/sampling_settings/presentation/sampling_settings_page.dart';
 import 'package:faro_example/features/tracing/presentation/tracing_page.dart';
 import 'package:faro_example/features/user_actions/presentation/user_actions_page.dart';
 import 'package:faro_example/features/user_settings/user_settings_page.dart';
 import 'package:faro_example/features/user_settings/user_settings_service.dart';
+import 'package:faro_example/qa_config.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:shared_preferences/shared_preferences.dart';
-import 'package:faro_example/features/network_requests/presentation/network_requests_page.dart';
 
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
@@ -46,6 +47,21 @@ void main() async {
   const faroCollectorUrl = String.fromEnvironment('FARO_COLLECTOR_URL');
   final faroApiKey = faroCollectorUrl.split('/').last;
 
+  final qaConfig = QaConfig.fromEnvironment();
+
+  final sessionAttributes = <String, Object>{
+    'team': 'mobile',
+    'department': 'engineering',
+    'test_int': 42,
+    'test_bool': true,
+    'test_double': 3.14,
+    if (qaConfig.hasRunId) 'qa_run_id': qaConfig.runId!,
+  };
+
+  final initialUser = qaConfig.hasInitialUser
+      ? qaConfig.initialUser
+      : userSettingsService.initialUser;
+
   Faro().transports.add(OfflineTransport(
         maxCacheDuration: const Duration(days: 3),
       ));
@@ -57,7 +73,6 @@ void main() async {
       appEnv: 'Test',
       apiKey: faroApiKey,
       namespace: 'flutter_app',
-      // Sampling is configured via SamplingSettingsService
       sampling: samplingSettingsService.sampling,
       anrTracking: true,
       cpuUsageVitals: true,
@@ -66,14 +81,8 @@ void main() async {
       memoryUsageVitals: true,
       refreshRateVitals: true,
       fetchVitalsInterval: const Duration(seconds: 30),
-      sessionAttributes: {
-        'team': 'mobile',
-        'department': 'engineering',
-        'test_int': 42,
-        'test_bool': true,
-        'test_double': 3.14,
-      },
-      initialUser: userSettingsService.initialUser,
+      sessionAttributes: sessionAttributes,
+      initialUser: initialUser,
       persistUser: userSettingsService.persistUser,
     ),
     appRunner: () async {

example/lib/qa_config.dart

@@ -0,0 +1,90 @@
+import 'dart:convert';
+
+import 'package:faro/faro.dart';
+
+/// Configuration parsed from optional QA dart-define keys.
+///
+/// Reads `FARO_QA_RUN_ID` and `FARO_QA_INITIAL_USER_JSON` from
+/// `String.fromEnvironment`, allowing QA smoke tests to inject
+/// session attributes and an initial user without patching source code.
+///
+/// Usage in production code:
+/// ```dart
+/// final qa = QaConfig.fromEnvironment();
+/// ```
+///
+/// Usage in tests (inject values directly):
+/// ```dart
+/// final qa = QaConfig.parse(qaRunId: 'run-42');
+/// ```
+class QaConfig {
+  const QaConfig._({this.runId, this.initialUser});
+
+  /// A QA-assigned run identifier included in session attributes.
+  final String? runId;
+
+  /// A [FaroUser] parsed from JSON, used as `initialUser` when present.
+  final FaroUser? initialUser;
+
+  /// Whether a QA run ID was provided.
+  bool get hasRunId => runId != null && runId!.isNotEmpty;
+
+  /// Whether a QA initial user was provided.
+  bool get hasInitialUser => initialUser != null;
+
+  /// Reads QA config from compile-time dart-define environment variables.
+  ///
+  /// Equivalent to `parse()` with defaults wired to `String.fromEnvironment`.
+  static QaConfig fromEnvironment() {
+    return parse(
+      qaRunId: const String.fromEnvironment('FARO_QA_RUN_ID'),
+      qaInitialUserJson:
+          const String.fromEnvironment('FARO_QA_INITIAL_USER_JSON'),
+    );
+  }
+
+  /// Parses QA configuration from raw string values.
+  ///
+  /// Empty strings are treated as "not provided".
+  /// Invalid JSON in [qaInitialUserJson] is silently ignored (returns
+  /// a config with no initial user).
+  static QaConfig parse({
+    String qaRunId = '',
+    String qaInitialUserJson = '',
+  }) {
+    final runId = qaRunId.isNotEmpty ? qaRunId : null;
+    final user = _parseUser(qaInitialUserJson);
+    return QaConfig._(runId: runId, initialUser: user);
+  }
+
+  static FaroUser? _parseUser(String json) {
+    if (json.isEmpty) return null;
+
+    try {
+      final decoded = jsonDecode(json);
+      if (decoded is! Map<String, dynamic>) return null;
+
+      return FaroUser(
+        id: decoded['id'] is String ? decoded['id'] as String : null,
+        username: decoded['username'] is String
+            ? decoded['username'] as String
+            : null,
+        email: decoded['email'] is String ? decoded['email'] as String : null,
+        attributes: _parseAttributes(decoded['attributes']),
+      );
+    } on FormatException {
+      return null;
+    }
+  }
+
+  /// Converts an attributes map to `Map<String, String>`, coercing
+  /// primitive values (bool, int, double) to their string representation.
+  static Map<String, String>? _parseAttributes(dynamic raw) {
+    if (raw == null) return null;
+    if (raw is! Map) return null;
+
+    return raw.map<String, String>(
+      (key, value) => MapEntry(key.toString(), value.toString()),
+    );
+  }
+}