Support mocking feature flags and add test coverage (#278)

## Ticket

Resolves #263

---------

Co-authored-by: Sawyer <[email protected]>

Author: jcq

app/.env.development

@@ -6,8 +6,15 @@
 # If you deploy to a subpath, change this to the subpath so relative paths work correctly.
 NEXT_PUBLIC_BASE_PATH=
 
-# AWS Evidently Feature Flag variables
+# =====================================================
+# AWS Evidently feature flagging service
+# =====================================================
 AWS_ACCESS_KEY_ID=
 AWS_SECRET_ACCESS_KEY=
 FEATURE_FLAGS_PROJECT=
-AWS_REGION=
+AWS_REGION=
+
+# When FEATURE_FLAGS_PROJECT isn't set, a mock feature flagging service is used.
+# You can mock a feature flag's value by setting it here, using an env var name
+# format like NEXT_PUBLIC_FEATURE_<feature_name>=<true|false>
+# NEXT_PUBLIC_FEATURE_foo=true

app/README.md

@@ -15,14 +15,15 @@
 │   │   ├── api       # Custom request handlers
 │   │   ├── layout.tsx # Root layout, wraps every page
 │   │   └── page.tsx  # Homepage
+|   ├── adapters      # External service adapters
 │   ├── components    # Reusable UI components
 │   ├── i18n          # Internationalization
-│   │   ├── config.ts # Supported locales, timezone, and formatters
+│   │   ├── config.ts  # Supported locales, timezone, and formatters
 │   │   └── messages  # Translated strings
 │   ├── styles        # Sass & design system settings
 │   └── types         # TypeScript type declarations
 ├── stories           # Storybook pages
-└── tests
+└── tests             # Test setup and helpers
 ```
 
 ## 💻 Development

app/src/adapters/feature-flags/EvidentlyAdapter.test.ts

@@ -0,0 +1,50 @@
+import { Evidently } from "@aws-sdk/client-evidently";
+
+import { EvidentlyAdapter } from "./EvidentlyAdapter";
+
+function getMockClient(flagValue: boolean) {
+  return {
+    evaluateFeature: jest.fn().mockResolvedValue({
+      value: {
+        boolValue: flagValue,
+      },
+      reason: "test-reason",
+    }),
+  } as unknown as Evidently;
+}
+
+describe("EvidentlyAdapter", () => {
+  beforeAll(() => {
+    // Disable logging in test output
+    jest.spyOn(console, "log").mockImplementation(() => {});
+    jest.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  describe("isFeatureEnabled", () => {
+    it("falls back to false if the feature flag evaluation fails", async () => {
+      const client = getMockClient(true);
+      client.evaluateFeature = jest
+        .fn()
+        .mockRejectedValue(new Error("test-error"));
+      const adapter = new EvidentlyAdapter();
+
+      const result = await adapter.isFeatureEnabled("test-feature");
+
+      expect(result).toBe(false);
+    });
+
+    it.each([true, false])(
+      "returns the boolean value of the feature flag evaluation",
+      async (flagValue) => {
+        const adapter = new EvidentlyAdapter(getMockClient(flagValue));
+
+        const result = await adapter.isFeatureEnabled(
+          "test-feature",
+          "test-entity-id"
+        );
+
+        expect(result).toBe(flagValue);
+      }
+    );
+  });
+});

app/src/services/feature-flags/FeatureFlagManager.ts renamed to app/src/adapters/feature-flags/EvidentlyAdapter.ts

@@ -1,23 +1,24 @@
 import { Evidently } from "@aws-sdk/client-evidently";
 
+import { FeatureFlagAdapter } from "./types";
+
 /**
  * Class for managing feature flagging via AWS Evidently.
  * Class method are available for use in next.js server side code.
  *
  * https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/evidently/
- *
  */
-export class FeatureFlagManager {
+export class EvidentlyAdapter implements FeatureFlagAdapter {
   client: Evidently;
   private _project = process.env.FEATURE_FLAGS_PROJECT;
 
-  constructor() {
-    this.client = new Evidently();
+  constructor(client = new Evidently()) {
+    this.client = client;
   }
 
-  async isFeatureEnabled(featureName: string, userId?: string) {
+  async isFeatureEnabled(featureName: string, entityId = "unknown") {
     const evalRequest = {
-      entityId: userId,
+      entityId,
       feature: featureName,
       project: this._project,
     };
@@ -31,7 +32,7 @@ export class FeatureFlagManager {
           message: "Made feature flag evaluation with AWS Evidently",
           data: {
             reason: evaluation.reason,
-            userId: userId,
+            entityId,
             featureName: featureName,
             featureFlagValue: featureFlagValue,
           },
@@ -42,8 +43,8 @@ export class FeatureFlagManager {
         message: "Error retrieving feature flag variation from AWS Evidently",
         data: {
           err: e,
-          userId: userId,
-          featureName: featureName,
+          entityId,
+          featureName,
         },
       });
     }

app/src/adapters/feature-flags/MockAdapter.test.ts

@@ -0,0 +1,38 @@
+import { MockAdapter } from "./MockAdapter";
+
+const mockAdapter = new MockAdapter();
+
+describe("MockAdapter", () => {
+  describe("isFeatureEnabled", () => {
+    it("returns true when env var is set to true", async () => {
+      process.env.NEXT_PUBLIC_FEATURE_baz = "true";
+
+      const isEnabled = await mockAdapter.isFeatureEnabled("baz");
+
+      expect(isEnabled).toBe(true);
+    });
+
+    it("returns true when env var is set to TRUE", async () => {
+      process.env.NEXT_PUBLIC_FEATURE_baz = "TRUE";
+
+      const isEnabled = await mockAdapter.isFeatureEnabled("baz");
+
+      expect(isEnabled).toBe(true);
+    });
+
+    it("returns false when env var is set to false", async () => {
+      process.env.NEXT_PUBLIC_FEATURE_baz = "false";
+
+      const isEnabled = await mockAdapter.isFeatureEnabled("baz");
+
+      expect(isEnabled).toBe(false);
+    });
+
+    it("returns false when an env var is not set", async () => {
+      delete process.env.NEXT_PUBLIC_FEATURE_baz;
+      const isEnabled = await mockAdapter.isFeatureEnabled("baz");
+
+      expect(isEnabled).toBe(false);
+    });
+  });
+});

app/src/adapters/feature-flags/MockAdapter.ts

@@ -0,0 +1,23 @@
+import { FeatureFlagAdapter } from "./types";
+
+/**
+ * Mocks feature flag responses based on environment variables.
+ * Only intended for local development or testing.
+ */
+export class MockAdapter implements FeatureFlagAdapter {
+  async isFeatureEnabled(featureName: string, entityId?: string) {
+    const envVarName = `NEXT_PUBLIC_FEATURE_${featureName}`;
+    const isEnabled = process.env[envVarName]?.toLowerCase() === "true";
+
+    if (process.env.NODE_ENV !== "test") {
+      console.warn("Using mock feature flag adapter", {
+        envVarName,
+        featureName,
+        isEnabled,
+        entityId,
+      });
+    }
+
+    return Promise.resolve(isEnabled);
+  }
+}

app/src/adapters/feature-flags/index.ts

@@ -0,0 +1,10 @@
+import { adapter } from "./setup";
+
+/**
+ * Check if a feature flag is enabled
+ * @param featureName - Name of the flag
+ * @param entityId - Optional id (e.g. user id) to use for phased rollouts
+ */
+export function isFeatureEnabled(featureName: string, entityId?: string) {
+  return adapter.isFeatureEnabled(featureName, entityId);
+}

app/src/adapters/feature-flags/setup.ts

@@ -0,0 +1,7 @@
+import { EvidentlyAdapter } from "./EvidentlyAdapter";
+import { MockAdapter } from "./MockAdapter";
+import { FeatureFlagAdapter } from "./types";
+
+export const adapter: FeatureFlagAdapter = process.env.FEATURE_FLAGS_PROJECT
+  ? new EvidentlyAdapter()
+  : new MockAdapter();

app/src/adapters/feature-flags/types.ts

@@ -0,0 +1,3 @@
+export interface FeatureFlagAdapter {
+  isFeatureEnabled(featureName: string, entityId?: string): Promise<boolean>;
+}

app/src/app/[locale]/page.test.tsx

@@ -1,21 +1,36 @@
 import { axe } from "jest-axe";
-import { LocalFeatureFlagManager } from "src/services/feature-flags/LocalFeatureFlagManager";
 import { cleanup, render, screen } from "tests/react-utils";
+import { mockFeatureFlag } from "tests/server-utils";
 
 import Controller from "./page";
 import { View } from "./view";
 
 describe("Index - Controller", () => {
-  it("retrieves feature flags", async () => {
-    const featureFlagSpy = jest
-      .spyOn(LocalFeatureFlagManager.prototype, "isFeatureEnabled")
-      .mockResolvedValue(true);
+  describe("local feature flags", () => {
+    it("renders correctly based on local feature flag is unset", async () => {
+      const result = await Controller();
+      render(result);
 
-    const result = await Controller();
-    render(result);
+      expect(await screen.findByText(/flag is disabled/i)).toBeInTheDocument();
+    });
 
-    expect(featureFlagSpy).toHaveBeenCalledWith("foo", "anonymous");
-    expect(screen.getByText(/Flag is enabled/)).toBeInTheDocument();
+    it("renders correctly based on local feature flag is true", async () => {
+      mockFeatureFlag("foo", true);
+
+      const result = await Controller();
+      render(result);
+
+      expect(await screen.findByText(/flag is enabled/i)).toBeInTheDocument();
+    });
+
+    it("renders correctly based on local feature flag is false", async () => {
+      mockFeatureFlag("foo", false);
+
+      const result = await Controller();
+      render(result);
+
+      expect(await screen.findByText(/flag is disabled/i)).toBeInTheDocument();
+    });
   });
 });