test: add E2E tests for /v1/models endpoint (opendatahub-io#509)

## Description
<!--- Describe your changes in detail -->
This PR adds comprehensive E2E test coverage for the `/v1/models`
endpoint that validates subscription-aware model filtering and access
control.
**Test Coverage:**
- **Single subscription auto-selection**: Users with one subscription
can list models without providing `x-maas-subscription` header
- **Explicit subscription header**: Users with multiple subscriptions
can select which subscription to use
- **Multiple subscriptions requiring header**: Validates proper 403
error when header is missing
- **Subscription filtering and validation**: Ensures models are filtered
by subscription access
- **Model deduplication scenarios**: Tests handling of multiple
modelRefs serving the same model
- **Empty model lists**: Validates response when user has no accessible
models
- **Response schema validation**: Ensures API responses match
OpenAI-compatible schema
- **Error cases**: Tests 401 (unauthenticated) and 403 (forbidden)
scenarios
**Sample Resources:**
- Added two distinct test models (`e2e-distinct-simulated`,
`e2e-distinct-2-simulated`) to enable multi-model subscription testing
- Added corresponding MaaSModelRef kustomize configurations for test
deployment
**Known Issues (marked as xfail):**
Three tests expose a known bug where `/v1/models` returns all accessible
models instead of filtering by the selected subscription. These are
marked with `@pytest.mark.xfail` and will
pass once the filtering bug is fixed:
- `test_single_subscription_auto_select`
  - `test_explicit_subscription_header`
  - `test_multiple_distinct_models_in_subscription`

  ## How Has This Been Tested?
  <!--- Please describe in detail how you tested your changes. -->
<!--- Include details of your testing environment, and the tests you ran
to -->
  <!--- see how your change affects other areas of the code, etc. -->

  **Test Execution:**
  ```bash
  cd test/e2e
  ./scripts/prow_run_smoke_test.sh

  Results:
  - 12 tests passed
  - 3 tests xfailed (expected failures due to known bug)
  - 0 tests failed
  - All tests run in isolated namespaces with proper cleanup

  Environment:
  - OpenShift cluster with MaaS components deployed
  - maas-controller watching models-as-a-service namespace
  - Models deployed in llm namespace
  - Kuadrant/Authorino for authorization
  - PostgreSQL backend for API key storage

  Validation:
  - Verified subscription-based access control works correctly
  - Verified API key authentication flow
  - Verified OpenAI-compatible response format
  - Verified proper error handling for unauthorized access


## Merge criteria:
<!--- This PR will be merged by any repository approver when it meets
all the points in the checklist -->
<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [x] The commits are squashed in a cohesive manner and have meaningful
messages.
- [x] Testing instructions have been added in the PR body (for PRs
involving changes that are not immediately obvious).
- [x] The developer has manually tested the changes and verified that
the changes work


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added sample Kustomize and model manifests (including MaaSModelRef) to
demonstrate distinct multi-model deployments and updated top-level
samples to include distinct and distinct-2 entries.
* **Tests**
* Added comprehensive end-to-end tests for the /v1/models endpoint
covering subscription-aware filtering, multi-model scenarios, auth/error
paths and deduplication checks; updated test runner to include them and
added env vars to support multi-model testing.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: jrhyness

docs/samples/maas-system/kustomization.yaml

@@ -2,11 +2,9 @@
 # per tier. Deploy all at once so dependencies resolve correctly.
 # - free: system:authenticated, 100 tokens/min
 # - premium: premium-user, 1000 tokens/min
-# - unconfigured: no auth/subscription (e2e tests validate 403)
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 
 resources:
   - free
   - premium
-  - unconfigured

docs/samples/models/e2e-distinct-2-simulated/kustomization.yaml

@@ -0,0 +1,7 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+namespace: llm
+
+resources:
+  - model.yaml

docs/samples/models/e2e-distinct-2-simulated/model.yaml

@@ -0,0 +1,65 @@
+apiVersion: serving.kserve.io/v1alpha1
+kind: LLMInferenceService
+metadata:
+  name: e2e-distinct-2-simulated
+spec:
+  model:
+    uri: hf://sshleifer/tiny-gpt2 # ~2MB test model, simulator ignores it anyway
+    name: test/e2e-distinct-model-2
+  replicas: 1
+  router:
+    route: {}
+    # Connect to MaaS-enabled gateway
+    gateway:
+      refs:
+        - name: maas-default-gateway
+          namespace: openshift-ingress
+  template:
+    containers:
+      - name: main
+        image: "ghcr.io/llm-d/llm-d-inference-sim:v0.7.1"
+        imagePullPolicy: Always
+        command: ["/app/llm-d-inference-sim"]
+        args:
+        - --port
+        - "8000"
+        - --model
+        - test/e2e-distinct-model-2
+        - --mode
+        - random
+        - --ssl-certfile
+        - /var/run/kserve/tls/tls.crt
+        - --ssl-keyfile
+        - /var/run/kserve/tls/tls.key
+        env:
+          - name: POD_NAME
+            valueFrom:
+              fieldRef:
+                apiVersion: v1
+                fieldPath: metadata.name
+          - name: POD_NAMESPACE
+            valueFrom:
+              fieldRef:
+                apiVersion: v1
+                fieldPath: metadata.namespace
+        ports:
+          - name: https
+            containerPort: 8000
+            protocol: TCP
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: https
+            scheme: HTTPS
+        resources:
+          requests:
+            cpu: 100m
+            memory: 256Mi
+          limits:
+            cpu: 500m
+            memory: 512Mi
+        readinessProbe:
+          httpGet:
+            path: /ready
+            port: https
+            scheme: HTTPS

docs/samples/models/e2e-distinct-simulated/kustomization.yaml

@@ -0,0 +1,7 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+namespace: llm
+
+resources:
+  - model.yaml

docs/samples/models/e2e-distinct-simulated/model.yaml

@@ -0,0 +1,65 @@
+apiVersion: serving.kserve.io/v1alpha1
+kind: LLMInferenceService
+metadata:
+  name: e2e-distinct-simulated
+spec:
+  model:
+    uri: hf://sshleifer/tiny-gpt2 # ~2MB test model, simulator ignores it anyway
+    name: test/e2e-distinct-model
+  replicas: 1
+  router:
+    route: {}
+    # Connect to MaaS-enabled gateway
+    gateway:
+      refs:
+        - name: maas-default-gateway
+          namespace: openshift-ingress
+  template:
+    containers:
+      - name: main
+        image: "ghcr.io/llm-d/llm-d-inference-sim:v0.7.1"
+        imagePullPolicy: Always
+        command: ["/app/llm-d-inference-sim"]
+        args:
+        - --port
+        - "8000"
+        - --model
+        - test/e2e-distinct-model
+        - --mode
+        - random
+        - --ssl-certfile
+        - /var/run/kserve/tls/tls.crt
+        - --ssl-keyfile
+        - /var/run/kserve/tls/tls.key
+        env:
+          - name: POD_NAME
+            valueFrom:
+              fieldRef:
+                apiVersion: v1
+                fieldPath: metadata.name
+          - name: POD_NAMESPACE
+            valueFrom:
+              fieldRef:
+                apiVersion: v1
+                fieldPath: metadata.namespace
+        ports:
+          - name: https
+            containerPort: 8000
+            protocol: TCP
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: https
+            scheme: HTTPS
+        resources:
+          requests:
+            cpu: 100m
+            memory: 256Mi
+          limits:
+            cpu: 500m
+            memory: 512Mi
+        readinessProbe:
+          httpGet:
+            path: /ready
+            port: https
+            scheme: HTTPS

test/e2e/README.md

@@ -75,15 +75,67 @@ cd test/e2e
 
 Results: `test/e2e/reports/api-keys-report.html`
 
+### Models Endpoint Tests
+
+Tests for the `/v1/models` endpoint that validate subscription-aware model filtering:
+
+```bash
+cd test/e2e
+source .venv/bin/activate
+
+# Run all /v1/models tests
+pytest tests/test_models_endpoint.py -v
+
+# Run specific test scenarios
+pytest tests/test_models_endpoint.py::TestModelsEndpoint::test_single_subscription_auto_select -v
+pytest tests/test_models_endpoint.py::TestModelsEndpoint::test_multi_subscription_without_header_403 -v
+```
+
+**Test Coverage (15 tests):**
+
+*Success Cases (HTTP 200) - 11 tests:*
+- ✅ Single subscription auto-select (no header required)
+- ✅ Explicit subscription header with multiple subscriptions
+- ✅ Empty subscription header value behavior
+- ✅ Subscription header case insensitivity (HTTP standard)
+- ✅ Models correctly filtered by subscription
+- ⚠️  Same modelRef listed twice should deduplicate (xfail - returns 2+ duplicates instead of 1)
+- ⚠️  Different modelRefs serving SAME model ID should deduplicate (xfail - returns 3+ duplicates instead of 1)
+- ✅ Different modelRefs with different IDs returns 2 entries (uses non-duplicating simulators)
+- ⚠️  Empty model list returns [] not null (xfail - currently returns null)
+- ✅ Response schema matches OpenAPI specification
+- ✅ Model metadata (url, ready, created, owned_by) preserved
+
+*Error Cases (HTTP 403) - 3 tests:*
+- ✅ Multiple subscriptions without header → 403 permission_error
+- ✅ Invalid subscription header → 403 permission_error
+- ✅ Access denied to subscription → 403 permission_error
+
+*Error Cases (HTTP 401) - 1 test:*
+- ✅ Unauthenticated request → 401 authentication_error
+
+**What's Being Validated:**
+The `/v1/models` endpoint implements subscription-aware model filtering:
+- Users with a single subscription don't need to specify `x-maas-subscription` header
+- Users with multiple subscriptions must use `x-maas-subscription` header to select
+- Returns proper error responses (403/401) with `permission_error`/`authentication_error` types
+- Models are correctly filtered to only show those from the specified subscription
+- Response structure matches OpenAPI schema: `{"object": "list", "data": [...]}`
+- HTTP header handling follows standards (case-insensitive)
+- Model metadata is accurately preserved from source
+
 ## CI Integration
 
 These tests run automatically in CI via:
-- **Prow**: `./test/e2e/scripts/prow_run_smoke_test.sh` (includes subscription tests)
+- **Prow**: `./test/e2e/scripts/prow_run_smoke_test.sh` (includes all E2E tests)
 - **GitHub Actions**: Can be integrated into `.github/workflows/` as needed
 
 The `prow_run_smoke_test.sh` script:
 1. Deploys MaaS platform and dependencies
 2. Deploys test models (free + premium simulators)
-3. Runs subscription controller tests (`test_subscription.py`)
+3. Runs E2E tests:
+   - API key management (`test_api_keys.py`)
+   - Subscription controller (`test_subscription.py`)
+   - Models endpoint (`test_models_endpoint.py`)
 4. Runs deployment validation and token metadata verification
 5. Collects artifacts (HTML/XML reports, logs) to `ARTIFACT_DIR`

test/e2e/fixtures/README.md

@@ -0,0 +1,36 @@
+# E2E Test Fixtures
+
+This directory contains kustomizations for end-to-end testing that combine public samples with test-only fixtures.
+
+## Contents
+
+### Public Samples (from `docs/samples/maas-system/`)
+- **free**: `system:authenticated` group, 100 tokens/min
+- **premium**: `premium-user` group, 1000 tokens/min
+
+### Test-Only Fixtures
+- **unconfigured**: Model with no MaaSAuthPolicy or MaaSSubscription (validates that gateway denies access with 403)
+- **distinct**: First distinct model serving `test/e2e-distinct-model` (validates multiple distinct models in subscriptions)
+- **distinct-2**: Second distinct model serving `test/e2e-distinct-model-2` (validates multiple distinct models in subscriptions)
+
+## Usage
+
+### For E2E Tests (CI)
+
+```bash
+# Deploy all fixtures (public samples + test-only)
+kustomize build test/e2e/fixtures | kubectl apply -f -
+```
+
+### For Manual Testing
+
+To deploy only the public samples without test fixtures, use:
+
+```bash
+# Public samples only (free + premium)
+kustomize build docs/samples/maas-system | kubectl apply -f -
+```
+
+## Note
+
+⚠️ **Do not use this kustomization for production or sample installations.** It includes test-only models that are designed to validate edge cases and should not be deployed in normal usage scenarios. For sample installations, use `docs/samples/maas-system/` instead.

test/e2e/fixtures/distinct-2/kustomization.yaml

@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - llm
+  - maas

test/e2e/fixtures/distinct-2/llm/kustomization.yaml

@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../../../../docs/samples/models/e2e-distinct-2-simulated