test(flagd): adopt the OpenFeature Provider TCK

Runs the conformance suite against the flagd provider in both resolver modes.
The whole adoption is a shared abstract base and two subclasses that differ only
in resolver and port: the TCK brings its own Gherkin, its own step definitions
and its own Compose lifecycle, and works out which suite is running from the
JUnit test plan, so a mode needs no registration and no build configuration.

The Compose stack wraps the unmodified flagd-testbed image, which already serves
both flagd and the launchpad control API that this TCK's control API contract was
derived from. No host port bindings: the TCK discovers dynamically mapped ports
after startup, so the suite runs in parallel and does not collide with a
developer's local flagd.

capabilities() is declarableExcept(NUMERIC_COERCION). Evaluating float-flag (0.5)
through the integer API returns 0 with no error code rather than TYPE_MISMATCH
with the code default -- the value is silently truncated. Coercion as such is
permitted; it is the lossy case being accepted that is the defect, tracked as
open-feature/flagd#1996. Both resolvers behave identically, which places it in
the shared provider layer rather than in either transport, so it is declared once
here. Delete the override when the defect is fixed.

Split out of #1830 so that the suite and its first adopter are reviewed as
separate questions: whether the TCK is the right contract, and whether flagd
satisfies it.

Signed-off-by: Simon Schrottner <simon.schrottner@flagsmith.com>

Author: aepfli

providers/flagd/pom.xml

@@ -22,6 +22,8 @@
         <com.vmlens.version>1.2.28</com.vmlens.version>
         <!-- Transitive flagd-core version -->
         <flagd-core.version>[2.0.0,3.0.0)</flagd-core.version>
+        <!-- Match any provider-tck version locally; CI resolves it from the reactor -->
+        <provider-tck.version>[0.0.1,)</provider-tck.version>
     </properties>
 
     <name>flagd</name>
@@ -98,6 +100,17 @@
             <version>5.14.3</version>
             <scope>test</scope>
         </dependency>
+        <!--
+            OpenFeature Provider TCK. Brings its own Gherkin, step definitions and Compose
+            lifecycle; FlagdTckTest is the whole adoption. Version range so a local reactor
+            build matches whatever is checked out.
+        -->
+        <dependency>
+            <groupId>dev.openfeature.contrib.tools</groupId>
+            <artifactId>provider-tck</artifactId>
+            <version>${provider-tck.version}</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.testcontainers</groupId>
             <artifactId>testcontainers</artifactId>

providers/flagd/src/test/java/dev/openfeature/contrib/providers/flagd/e2e/AbstractFlagdTckTest.java

@@ -0,0 +1,122 @@
+package dev.openfeature.contrib.providers.flagd.e2e;
+
+import dev.openfeature.contrib.providers.flagd.Config;
+import dev.openfeature.contrib.providers.flagd.FlagdOptions;
+import dev.openfeature.contrib.providers.flagd.FlagdProvider;
+import dev.openfeature.contrib.tools.providertck.BackendEndpoint;
+import dev.openfeature.contrib.tools.providertck.Capability;
+import dev.openfeature.contrib.tools.providertck.ContainerizedProviderTckTest;
+import dev.openfeature.sdk.FeatureProvider;
+import java.io.File;
+import java.util.Collections;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Shared configuration for running the OpenFeature Provider TCK against the flagd provider.
+ *
+ * <p>flagd resolves flags in two quite different ways, and both are worth conforming: RPC evaluates
+ * remotely over gRPC, while in-process syncs the ruleset and evaluates locally. They share a backend
+ * stack and differ only in resolver and port, so the modes are two small subclasses.
+ *
+ * <p>Each concrete subclass is its own JUnit suite and its own TCK harness; the TCK works out which
+ * one is running from the JUnit test plan, so adding a mode needs no registration or build
+ * configuration.
+ */
+abstract class AbstractFlagdTckTest extends ContainerizedProviderTckTest {
+
+    /**
+     * A port nothing listens on, for the initialisation-failure scenarios.
+     *
+     * <p>Deliberately not a port on the Compose stack: the stack must stay up for the whole suite,
+     * and simulated outages belong to the control API.
+     */
+    private static final int UNAVAILABLE_PORT = 9999;
+
+    /**
+     * gRPC deadline for a provider that is expected to connect.
+     *
+     * <p>Generous on purpose. flagd derives its initialisation deadline from this value, and the
+     * in-process resolver must sync the entire ruleset before it reports ready — which intermittently
+     * takes longer than a deadline tuned for a single RPC round trip.
+     */
+    private static final int CONNECTED_DEADLINE_MS = 5000;
+
+    /**
+     * gRPC deadline for a provider pointed at a dead port.
+     *
+     * <p>Short on purpose, and deliberately not the same as {@link #CONNECTED_DEADLINE_MS}: the
+     * initialisation-failure scenarios assert that the failure is reported <em>promptly</em>, so a
+     * provider that takes as long to give up as it does to connect would defeat the point.
+     */
+    private static final int UNAVAILABLE_DEADLINE_MS = 1000;
+
+    /** The resolver under test. */
+    protected abstract Config.Resolver resolver();
+
+    /** The container-internal port that resolver connects to. */
+    protected abstract int backendPort();
+
+    @Override
+    public File composeFile() {
+        return new File("src/test/resources/tck/docker-compose.yaml");
+    }
+
+    @Override
+    public List<Integer> backendPorts() {
+        return Collections.singletonList(backendPort());
+    }
+
+    @Override
+    public FeatureProvider createProvider(BackendEndpoint endpoint) {
+        return new FlagdProvider(baseOptions()
+                .deadline(CONNECTED_DEADLINE_MS)
+                .host(endpoint.host())
+                .port(endpoint.port(backendPort()))
+                .build());
+    }
+
+    @Override
+    public FeatureProvider createUnavailableProvider() {
+        return new FlagdProvider(baseOptions()
+                .deadline(UNAVAILABLE_DEADLINE_MS)
+                .host("localhost")
+                .port(UNAVAILABLE_PORT)
+                .build());
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Everything declarable except {@link Capability#NUMERIC_COERCION}. Evaluating
+     * {@code float-flag} (0.5) through the integer API returns {@code 0} with <em>no</em> error code
+     * rather than {@code TYPE_MISMATCH} with the code default — the value is silently truncated.
+     * Coercion as such is permitted, and the capability says so: the rule is that a lossless
+     * coercion must succeed and a lossy one must fail. It is the lossy case being accepted that is a
+     * defect to fix, not a design choice; this override should be deleted once it is.
+     *
+     * <p>Declared here rather than per mode because both resolvers behave identically, which places
+     * the defect in the shared provider layer rather than in either transport. Every other
+     * capability, including the full non-numeric type-mismatch matrix, holds in both modes.
+     *
+     * <p>That includes {@link Capability#LIFECYCLE}, and legitimately so: flagd reaches its backend
+     * during initialisation in both modes — an RPC round trip, or a full ruleset sync — so the
+     * lifecycle scenarios assert something real here rather than passing vacuously.
+     *
+     * <p>{@link Capability#declarableExcept} rather than {@code EnumSet.complementOf}, which is what
+     * this used to be. The complement of one capability is every other <em>enum constant</em>,
+     * including {@code @targeting} and {@code @caching} — reserved tags no scenario carries — so a
+     * report emitted from here claimed two capabilities nothing had examined.
+     */
+    @Override
+    public Set<Capability> capabilities() {
+        return Capability.declarableExcept(Capability.NUMERIC_COERCION);
+    }
+
+    private FlagdOptions.FlagdOptionsBuilder baseOptions() {
+        return FlagdOptions.builder()
+                .resolverType(resolver())
+                .retryGracePeriod(2)
+                .retryBackoffMs(500);
+    }
+}

providers/flagd/src/test/java/dev/openfeature/contrib/providers/flagd/e2e/FlagdInProcessTckTest.java

@@ -0,0 +1,17 @@
+package dev.openfeature.contrib.providers.flagd.e2e;
+
+import dev.openfeature.contrib.providers.flagd.Config;
+
+/** Runs the OpenFeature Provider TCK against the flagd provider in in-process mode. */
+public class FlagdInProcessTckTest extends AbstractFlagdTckTest {
+
+    @Override
+    protected Config.Resolver resolver() {
+        return Config.Resolver.IN_PROCESS;
+    }
+
+    @Override
+    protected int backendPort() {
+        return 8015;
+    }
+}

providers/flagd/src/test/java/dev/openfeature/contrib/providers/flagd/e2e/FlagdRpcTckTest.java

@@ -0,0 +1,17 @@
+package dev.openfeature.contrib.providers.flagd.e2e;
+
+import dev.openfeature.contrib.providers.flagd.Config;
+
+/** Runs the OpenFeature Provider TCK against the flagd provider in RPC mode. */
+public class FlagdRpcTckTest extends AbstractFlagdTckTest {
+
+    @Override
+    protected Config.Resolver resolver() {
+        return Config.Resolver.RPC;
+    }
+
+    @Override
+    protected int backendPort() {
+        return 8013;
+    }
+}

providers/flagd/src/test/resources/tck/docker-compose.yaml

@@ -0,0 +1,15 @@
+# Backend stack for the OpenFeature Provider TCK, wrapping the unmodified flagd testbed image.
+#
+# The image already serves everything the TCK needs: flagd itself, and the "launchpad" control
+# API on 8080 whose endpoints this TCK's control API contract was derived from.
+#
+# Note there are no host port bindings. The TCK requires dynamically mapped ports and discovers
+# them after startup — a pinned host port would make the suite unrunnable in parallel and would
+# collide with a developer's local flagd.
+services:
+  backend:
+    image: ghcr.io/open-feature/flagd-testbed:v3.8.0
+    ports:
+      - 8013   # flagd RPC evaluation (gRPC)
+      - 8015   # flagd in-process sync (gRPC)
+      - 8080   # launchpad control API