chore(ci): Add BDD Test framework (#2640)

### Proposed Changes

* Introduces BDD Testing Framework

### Checklist

- [ ] I have added or updated unit tests
- [ ] I have added or updated integration tests (if appropriate)
- [ ] I have added or updated documentation

### Testing Instructions

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: jhaage-virtru

.github/scripts/init-temp-keys.sh

@@ -60,7 +60,19 @@ openssl req -new -nodes -newkey rsa:2048 -keyout keys/sampleuser.key -out keys/s
 openssl x509 -req -in keys/sampleuser.req -CA keys/keycloak-ca.pem -CAkey keys/keycloak-ca-private.pem -CAcreateserial -out keys/sampleuser.crt -days 3650
 
 openssl pkcs12 -export -in keys/keycloak-ca.pem -inkey keys/keycloak-ca-private.pem -out keys/ca.p12 -nodes -passout pass:password
+
+# Use JAVA_OPTS_APPEND if set, otherwise default based on architecture
+# For Apple Silicon: export JAVA_OPTS_APPEND="-XX:UseSVE=0" before running this script
+if [ -n "$JAVA_OPTS_APPEND" ]; then
+  JAVA_ENV_OPTS="-e JAVA_TOOL_OPTIONS=$JAVA_OPTS_APPEND"
+elif [ "$(uname -m)" = "arm64" ]; then
+  JAVA_ENV_OPTS="-e JAVA_TOOL_OPTIONS=-XX:UseSVE=0"
+else
+  JAVA_ENV_OPTS=""
+fi
+
 docker run \
+  $JAVA_ENV_OPTS \
   -v $(pwd)/keys:/keys \
   --entrypoint keytool \
   --user $(id -u):$(id -g) \

.github/workflows/checks.yaml

@@ -39,6 +39,7 @@ jobs:
           - lib/fixtures
           - lib/flattening
           - lib/identifier
+          - tests-bdd
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.4.2
         with:
@@ -53,6 +54,7 @@ jobs:
             protocol/go/go.sum
             sdk/go.sum
             service/go.sum
+            tests-bdd/go.sum
       - if: env.IS_RELEASE_BRANCH == 'true'
         name: prevent depending on unreleased upstream changes
         run: ./.github/scripts/work-init.sh
@@ -393,6 +395,64 @@ jobs:
       focus-sdk: go
       # use commit instead of ref so we can "go get" specific sdk version
       platform-ref: ${{ github.event.pull_request.head.sha || github.sha }} lts
+  
+  tests-bdd:
+    name: Cucumber BDD Tests
+    runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Install Dependencies
+        run: |
+          sudo apt-get update
+          # Remove containerd if present to prevent conflict
+          sudo apt-get remove -y containerd containerd.io || true
+          sudo apt-get install -y curl docker.io docker-compose-v2 lsof coreutils libnss3-tools
+          curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
+          chmod +x mkcert-v*-linux-amd64
+          sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert
+
+      - name: "Checkout"
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.4.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        with:
+          go-version-file: ./tests-bdd/go.mod
+          cache: false
+      
+      - name: Build local platform-cukes image for testing
+        run: docker build -t platform-cukes .
+
+      - name: Run BDD Tests
+        run: |
+          CUKES_LOG_HANDLER=console go test ./tests-bdd -v --tags=cukes --godog.random --godog.format="cucumber:$(pwd)/cukes_platform_report.json,pretty:$(pwd)/cukes_platform_report.log,pretty" ./features
+      
+      - name: Check for undefined steps
+        run: |
+          if grep -qi "Undefined" cukes_platform_report.log; then
+            echo "❌ Undefined steps found in BDD tests!"
+            exit 1
+          fi
+      
+      - name: Get logs on failure
+        if: failure() || cancelled()
+        run: |
+          echo "********** Cukes Platform Compose log **********"
+          cat cukes_platform_compose.log
+          echo "********** Docker logs **********"
+          docker ps -aq | xargs -L 1 docker logs
+      - uses: actions/upload-artifact@0b2256b8c012f0828dc542b3febcab082c67f72b # v4.3.4
+        if: ${{ !cancelled() }}
+        with:
+          name: cukes-report
+          path: |
+            cukes_platform_report.json
+            cukes_platform_report.log
+          retention-days: 1
 
   # test latest otdfctl CLI 'main' against platform PR branch
   otdfctl-test:
@@ -467,6 +527,7 @@ jobs:
       - benchmark
       - license
       - platform-xtest
+      - tests-bdd
       - otdfctl-test
     runs-on: ubuntu-22.04
     if: ${{ !cancelled() }}

.gitignore

@@ -47,3 +47,6 @@ keys/
 /examples/sensitive.txt.ntdf
 sensitive.txt.ntdf
 traces/
+
+# Cucumber / BDD log files
+*.log

Dockerfile

@@ -8,6 +8,7 @@ COPY sdk/ sdk/
 COPY lib/ lib/
 COPY service/ service/
 COPY examples/ examples/
+COPY tests-bdd/ tests-bdd/
 COPY go.work ./
 RUN cd service \
     && go mod download \

README.md

@@ -38,7 +38,7 @@ brew install buf go golangci-lint
 #### Optional tools
 
 - _Optional_ [Air](https://github.com/cosmtrek/air) is used for hot-reload development
-  - install with `go install github.com/cosmtrek/air@latest`
+  - install with `go install github.com/air-verse/air@latest`
 - _Optional_ [grpcurl](https://github.com/fullstorydev/grpcurl) is used for testing gRPC services
   - install with `brew install grpcurl`
 - _Optional_ [openssl](https://www.openssl.org/) is used for generating certificates
@@ -52,7 +52,7 @@ There are two primary audiences for this project. Consumers and Contributors
 Consumers of the OpenTDF platform should begin their journey [here](./docs/Consuming.md).
 
 2. Contributing
-To contribute to the OpenTDF platform, you'll need bit more set setup and should start [here](./docs/Contributing.md).
+To contribute to the OpenTDF platform, you'll need a bit more setup and should start [here](./docs/Contributing.md).
 
 ## Additional info for Project Consumers & Contributors
 
@@ -76,24 +76,23 @@ https://github.com/opentdf/platform/blob/main/service/go.mod#L3
 
 Generate development keys/certs for the platform infrastructure.
 
+> **Note for Apple M4 chip users:**  
+> If you are running on an Apple M4 chip, set the Java environment variable before running any commands:
+> ```sh
+> export JAVA_OPTS_APPEND="-XX:UseSVE=0"
+> ```
+> This resolves SIGILL with Code 134 errors when running Java processes.
+
 ```sh
 ./.github/scripts/init-temp-keys.sh
 ```
 
 Start the required infrastructure with [compose-spec](https://compose-spec.io).
 
 ```sh
-# If you are on an M4 chip (Apple Silicon), use the provided script to ensure the correct Java environment:
-./run-compose.sh -f docker-compose.yaml up
-
-# Otherwise, use docker compose directly:
 docker compose -f docker-compose.yaml up
 ```
 
-> **Note:**  
-> The `run-compose.sh` script is required on Apple Silicon (M1/M2/M3/M4) Macs to ensure the correct Java environment is used for containers that require x86_64 Java images.  
-> This is necessary because some images (such as Keycloak) may not have ARM-compatible builds, and the script sets up emulation as needed.
-
 Copy the development configuration file from the example and update it with your own values (if necessary, not common).
 
 ```sh
@@ -137,7 +136,7 @@ platform. The SDKs contain a native Go SDK and generated Go service SDKs. A full
 
 ### How To Add a New Go Module
 
-Within this repo, todefine a new, distinct [go module](https://go.dev/ref/mod),
+Within this repo, to define a new, distinct [go module](https://go.dev/ref/mod),
 for example to provide shared functionality between several existing modules,
 or to define new and unique functionality
 follow these steps.
@@ -198,7 +197,7 @@ COPY lib/foo/ lib/foo/
 
 #### Updating the Workflow Files
 
-1. Add your new `go.mod` directory to the `.github/workflows/checks.yaml`'s `go` job's `matrix.strategry.directory` line.
+1. Add your new `go.mod` directory to the `.github/workflows/checks.yaml`'s `go` job's `strategy.matrix.directory` line.
 2. Add the module to the `license` job in the `checks` workflow as well, especially if you declare _any_ dependencies.
 3. Do the same for any other workflows that should be running on your folder, such as `vuln-check` and `lint`.
 

docker-compose.yaml

@@ -4,9 +4,9 @@ networks:
 services:
   keycloak:
     volumes:
-    - ./keys/localhost.crt:/etc/x509/tls/localhost.crt
-    - ./keys/localhost.key:/etc/x509/tls/localhost.key
-    - ./keys/ca.jks:/truststore/truststore.jks
+    - ${KEYS_DIR:-./keys}/localhost.crt:/etc/x509/tls/localhost.crt
+    - ${KEYS_DIR:-./keys}/localhost.key:/etc/x509/tls/localhost.key
+    - ${KEYS_DIR:-./keys}/ca.jks:/truststore/truststore.jks
     image: keycloak/keycloak:25.0
     restart: always
     command:
@@ -43,17 +43,23 @@ services:
       KC_HTTPS_CERTIFICATE_KEY_FILE: "/etc/x509/tls/localhost.key"
       KC_HTTPS_CLIENT_AUTH: "request"
       ###
-      # If you are running on a M4 chip use the run-compose.sh script to start the containers
-      # The EXTRA_JAVA_OPTS variable allows users to pass additional Java options and is used by the run-compose.sh script
-      # to set the JAVA_OPTS_APPEND environment variable in the Keycloak container
-      JAVA_OPTS_APPEND: "${EXTRA_JAVA_OPTS}"
-      # OR comment the above line and uncomment the JAVA_OPTS_APPEND line below
-      # JAVA_OPTS_APPEND: "-XX:UseSVE=0" # Uncommenting resolves SIGILL with Code 134 when running on a machine with an M4 chip: https://github.com/keycloak/keycloak/issues/36008
+      # The following environment variable resolves SIGILL with Code 134 when running Java processes on Apple M4 chips
+      # 
+      # On Apple Silicon (M4 chip):
+      #   export JAVA_OPTS_APPEND="-XX:UseSVE=0"
+      #   docker-compose up
+      # 
+      # On other architectures:
+      #   export JAVA_OPTS_APPEND=""
+      #   docker-compose up
+      # 
+      # Or set directly: JAVA_OPTS_APPEND="-XX:UseSVE=0" docker-compose up
+      JAVA_OPTS_APPEND: "${JAVA_OPTS_APPEND:-}"
       ###
     ports:
-      - "9001:9001"
-      - "8888:8888"
-      - "8443:8443"
+      - "${KC_EXPOSE_PORT:-8443}:8443"
+      - "${KC_EXPOSE_PORT_HTTP:-8888}:8888"
+      - "${KC_EXPOSE_PORT_MGMT:-9001}:9001"
     healthcheck:
       test:
         - CMD-SHELL
@@ -73,7 +79,7 @@ services:
               java.net.HttpURLConnection conn = (java.net.HttpURLConnection)new java.net.URL(args[0]).openConnection(); 
               System.exit(java.net.HttpURLConnection.HTTP_OK == conn.getResponseCode() ? 0 : 1); 
             } 
-          }" > /tmp/HealthCheck.java && java /tmp/HealthCheck.java https://localhost:9001/auth/health/live
+          }" > /tmp/HealthCheck.java && java ${JAVA_OPTS_APPEND} /tmp/HealthCheck.java https://localhost:9001/auth/health/live
       timeout: 10s
       retries: 3
       start_period: 2m
@@ -91,7 +97,7 @@ services:
       timeout: 5s
       retries: 10
     ports:
-      - "5432:5432"
+      - "${POSTGRES_EXPOSE_PORT:-5432}:5432"
 
   jaeger:
     image: jaegertracing/all-in-one:latest

go.work

@@ -11,4 +11,5 @@ use (
 	./protocol/go
 	./sdk
 	./service
+	./tests-bdd
 )

run-compose.sh

@@ -22,17 +22,14 @@ const (
 	provKcInsecure     = "insecure"
 )
 
-var (
-	provKeycloakFilename = "./service/cmd/keycloak_data.yaml"
-	keycloakData         fixtures.KeycloakData
-)
+var provKeycloakFilename = "./service/cmd/keycloak_data.yaml"
 
 var provisionKeycloakCmd = &cobra.Command{
 	Use:   "keycloak",
 	Short: "Run local provision of keycloak data",
 	Long: `
 	** Local Development and Testing Only **
-	This command will create the following Keyclaok resource:
+	This command will create the following Keycloak resource:
 	- Realm
 	- Roles
 	- Client
@@ -46,7 +43,7 @@ var provisionKeycloakCmd = &cobra.Command{
 		kcPassword, _ := cmd.Flags().GetString(provKcPasswordFlag)
 		keycloakFilename, _ := cmd.Flags().GetString(provKcFilenameFlag)
 
-		LoadKeycloakData(keycloakFilename)
+		keycloakData := LoadKeycloakData(keycloakFilename)
 		ctx := context.Background()
 
 		kcParams := fixtures.KeycloakConnectParams{
@@ -94,7 +91,7 @@ func convert(i interface{}) interface{} {
 	return i
 }
 
-func LoadKeycloakData(file string) {
+func LoadKeycloakData(file string) fixtures.KeycloakData {
 	yamlData := make(map[interface{}]interface{})
 
 	f, err := os.Open(file)
@@ -118,11 +115,12 @@ func LoadKeycloakData(file string) {
 	if err != nil {
 		panic(fmt.Errorf("error converting yaml to json: %s", err.Error()))
 	}
-
+	var keycloakData fixtures.KeycloakData
 	if err := json.Unmarshal(kcData, &keycloakData); err != nil {
 		slog.Error("could not unmarshal json into data object", slog.String("error", err.Error()))
 		panic(err)
 	}
+	return keycloakData
 }
 
 func init() {