testing-fab

[mumenthalers]

Implement a configurable testing fab (floating action button) for angular frontends, that can be enabled on all non-prod systems and features an always on top floating action button, that brings options into view when activated. options that can be configured per app and allow certain config changes on the dev system; e.g. changing the backend env or showing all i18n keys instead of the translations. it needs to be configurable per app by providing e.g. a config for a "select that sets a query param" or simply a component that will be rendered in the expanded view of the fab

[mumenthalers]

Problem Statement

Consumer applications need a consistent way to expose non-production testing controls without repeatedly building ad-hoc debug UI. Today, there is no shared Library capability that provides an always-on-top entry point plus a standardized configuration model for runtime testing controls such as backend environment switching or i18n-key display mode.

Solution

Introduce a reusable Testing FAB capability in the Library that Consumer applications can explicitly enable via Opt-in Provisioning (provideTestingFab). The Testing FAB renders a floating action button that expands into a panel of Action Widgets. Initial Action Widget support includes Select Query Param Widget and Custom Component Widget, with URL-Authoritative Selection for query-param-backed controls. Activation safety remains Consumer-Owned Activation Safety (no implicit or environment-based auto-enable by the Library).

User Stories

1. As a frontend developer, I want to enable Testing FAB through one provider function, so that setup is explicit and easy to reason about.
2. As a frontend developer, I want Testing FAB to stay out of the app unless I register it, so that behavior is fully controlled by the Consumer.
3. As a QA engineer, I want an always-on-top floating entry point, so that I can access testing controls from any screen.
4. As a QA engineer, I want the button to expand into a panel, so that multiple testing controls can be grouped in one predictable place.
5. As a product engineer, I want Action Widgets to be configured declaratively, so that each app can define only the controls it needs.
6. As a product engineer, I want a Select Query Param Widget, so that I can switch between predefined runtime modes quickly.
7. As a product engineer, I want Select Query Param Widget values written to URL query parameters, so that the selected mode is shareable via deep links.
8. As a product engineer, I want the widget state to reflect URL values after reload, so that testing context persists naturally without extra storage.
9. As a QA engineer, I want to copy a URL and send it to a teammate, so that they can open the app in the same testing mode.
10. As a frontend developer, I want a Custom Component Widget, so that app-specific controls can be rendered in Testing FAB without modifying Library internals.
11. As a frontend developer, I want Custom Component Widget to support complex UI, so that advanced test scenarios can be encapsulated per app.
12. As a frontend developer, I want to mix multiple Action Widgets in one Testing FAB panel, so that all test controls are centrally discoverable.
13. As a frontend developer, I want stable configuration contracts for Action Widgets, so that upgrades do not break existing app-level configurations.
14. As a QA engineer, I want predictable open/close behavior for the panel, so that I can operate it quickly during scripted test runs.
15. As a frontend developer, I want no hidden environment checks in the Library, so that activation responsibility is explicit and testable in the Consumer.
16. As a frontend developer, I want Testing FAB integration to avoid global side effects when not provided, so that existing app behavior remains unchanged.
17. As a QA engineer, I want the panel controls to be visible and interactable in automated UI tests, so that testing workflows can be validated in CI.
18. As a frontend developer, I want query-param updates to be deterministic, so that behavior is reliable across navigation and refreshes.
19. As a frontend developer, I want a clear distinction between Testing FAB and production feature UI, so that team ownership and intent stay unambiguous.
20. As a maintainer, I want documented domain terms (Testing FAB, Action Widget, Select Query Param Widget, Custom Component Widget), so that contributors use a consistent ubiquitous language.
21. As a maintainer, I want the first release to focus on essential behavior only, so that delivery risk stays low and adoption can begin quickly.
22. As a frontend developer, I want a clear extension path for future Action Widget types, so that the model can evolve without redesigning the base API.
23. As a QA engineer, I want controls like backend-env switching and i18n key rendering mode to fit the same framework, so that app-level testing features look and behave consistently.
24. As a maintainer, I want Consumer-owned safety decisions to remain outside the Library core, so that shared code stays neutral and flexible across teams.

Implementation Decisions

• Provide a top-level configuration entry point named provideTestingFab(...) as the primary public contract.
• Use Opt-in Provisioning only; the Library must not auto-enable based on environment detection.
• Model Testing FAB content as a list of Action Widgets with a discriminated type shape.
• Implement the initial widget set as:
  • Select Query Param Widget for predefined value choices mapped to one query parameter.
  • Custom Component Widget for rendering Consumer-provided Angular components.
• Enforce URL-Authoritative Selection for Select Query Param Widget behavior: UI reflects URL value; selections update URL.
• Keep Consumer-Owned Activation Safety: production/non-production policy is decided in Consumer wiring, not in shared Library enforcement.
• Preserve backward-safe behavior: if Testing FAB is not provided, no UI, side effects, or routing changes are introduced.
• Keep panel interaction model minimal and predictable for MVP: floating trigger + expandable content container.
• Design Action Widget contracts for forward extension so future widget kinds can be added without changing existing config semantics.

Testing Decisions

• Good tests assert external behavior and public contract outcomes, not internal implementation details.
• Primary seam: provideTestingFab(...) integration behavior (provisioned vs not provisioned, visible Testing FAB behavior, and URL interaction effects).
• Verify that Select Query Param Widget:
  • Reads initial selection from URL query params.
  • Writes selection changes back to URL query params.
  • Reflects URL-driven changes consistently.
• Verify that Custom Component Widget renders the provided component and participates in panel lifecycle as expected.
• Verify no-op behavior when not provisioned (no visible Testing FAB, no unintended URL mutations).
• Prior art: existing provider-focused tests in this codebase validate behavior at DI/provider boundaries and runtime outcomes (e.g., provider factory behavior and guard/throw contracts), which aligns with this feature’s seam-first testing strategy.

Out of Scope

• Automatic environment-based enablement or disablement in Library code.
• Library-enforced production blocking.
• Dragging/repositioning the floating button.
• Permissions/role-based visibility logic.
• Remote configuration loading for widgets.
• Persistence mechanisms beyond URL query params for widget state.
• Additional widget types beyond Select Query Param Widget and Custom Component Widget in the first release.

Further Notes

• This PRD intentionally uses the project’s canonical language to avoid drift during implementation and review.
• The first release should optimize for low-friction adoption by Consumer apps and clear extension points for future Action Widget kinds.