feat(vcr): add JUnit 5 annotation-based VCR integration

Implements declarative VCR support via JUnit 5 annotations:

- @VCRModel: marks model fields for automatic VCR wrapping
- VCRModelWrapper: wraps LangChain4J and Spring AI models automatically
- VCRContext: manages Redis container, cassette store, and test state
- VCRExtension: JUnit 5 extension for lifecycle management

Features:
- VCR_MODE environment variable support for runtime mode override
- Automatic model detection (LangChain4J/Spring AI embedding/chat)
- Cassette store integration for Redis persistence
- Test isolation with per-test call counters
- Statistics tracking across test session

Example usage:
  @VCRTest(mode = VCRMode.PLAYBACK_OR_RECORD)
  class MyTest {
    @VCRModel
    private EmbeddingModel model = createModel();
  }

Author: bsbodden

core/src/main/java/com/redis/vl/test/vcr/VCRContext.java

@@ -35,6 +35,7 @@ public class VCRContext {
   private GenericContainer<?> redisContainer;
   private JedisPooled jedis;
   private VCRRegistry registry;
+  private VCRCassetteStore cassetteStore;
 
   private String currentTestId;
   private VCRMode effectiveMode;
@@ -46,15 +47,55 @@ public class VCRContext {
   private final AtomicLong cacheMisses = new AtomicLong();
   private final AtomicLong apiCalls = new AtomicLong();
 
+  /** Environment variable name for overriding VCR mode. */
+  public static final String VCR_MODE_ENV = "VCR_MODE";
+
   /**
    * Creates a new VCR context with the given configuration.
    *
+   * <p>The VCR mode can be overridden via the {@code VCR_MODE} environment variable. Valid values
+   * are: PLAYBACK, PLAYBACK_OR_RECORD, RECORD, OFF. If the environment variable is set, it takes
+   * precedence over the annotation's mode setting.
+   *
    * @param config the VCR test configuration
    */
   public VCRContext(VCRTest config) {
     this.config = config;
     this.dataDir = Path.of(config.dataDir());
-    this.effectiveMode = config.mode();
+    this.effectiveMode = resolveMode(config.mode());
+  }
+
+  /**
+   * Resolves the effective VCR mode, checking the environment variable first.
+   *
+   * @param annotationMode the mode specified in the annotation
+   * @return the effective mode (env var takes precedence)
+   */
+  private static VCRMode resolveMode(VCRMode annotationMode) {
+    String envMode = System.getenv(VCR_MODE_ENV);
+    if (envMode != null && !envMode.isEmpty()) {
+      try {
+        VCRMode mode = VCRMode.valueOf(envMode.toUpperCase());
+        System.out.println(
+            "VCR: Using mode from "
+                + VCR_MODE_ENV
+                + " environment variable: "
+                + mode
+                + " (annotation was: "
+                + annotationMode
+                + ")");
+        return mode;
+      } catch (IllegalArgumentException e) {
+        System.err.println(
+            "VCR: Invalid "
+                + VCR_MODE_ENV
+                + " value '"
+                + envMode
+                + "'. Valid values: PLAYBACK, PLAYBACK_OR_RECORD, RECORD, OFF. Using annotation value: "
+                + annotationMode);
+      }
+    }
+    return annotationMode;
   }
 
   /**
@@ -69,8 +110,21 @@ public void initialize() throws Exception {
     // Start Redis container with persistence
     startRedis();
 
-    // Initialize registry
+    // Initialize registry and cassette store
     registry = new VCRRegistry(jedis);
+    cassetteStore = new VCRCassetteStore(jedis);
+  }
+
+  /**
+   * Gets the cassette store for storing/retrieving cassettes.
+   *
+   * @return the cassette store
+   */
+  @SuppressFBWarnings(
+      value = "EI_EXPOSE_REP",
+      justification = "Callers need direct access to shared cassette store")
+  public VCRCassetteStore getCassetteStore() {
+    return cassetteStore;
   }
 
   /** Starts the Redis container with appropriate persistence configuration. */

core/src/main/java/com/redis/vl/test/vcr/VCRExtension.java

@@ -1,11 +1,16 @@
 package com.redis.vl.test.vcr;
 
+import java.lang.reflect.Field;
+import java.util.ArrayList;
+import java.util.List;
 import org.junit.jupiter.api.extension.AfterAllCallback;
 import org.junit.jupiter.api.extension.AfterEachCallback;
 import org.junit.jupiter.api.extension.BeforeAllCallback;
 import org.junit.jupiter.api.extension.BeforeEachCallback;
 import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.api.extension.TestWatcher;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 /**
  * JUnit 5 extension that provides VCR (Video Cassette Recorder) functionality for recording and
@@ -17,17 +22,33 @@
  *   <li>Redis container lifecycle with AOF/RDB persistence
  *   <li>Cassette storage and retrieval
  *   <li>Test context and call counter management
- *   <li>LLM call interception via ByteBuddy
+ *   <li>Automatic wrapping of {@code @VCRModel} annotated fields
  * </ul>
  *
- * <p>Usage:
+ * <p>Usage with declarative field wrapping:
  *
  * <pre>{@code
- * @VCRTest(mode = VCRMode.PLAYBACK)
+ * @VCRTest(mode = VCRMode.PLAYBACK_OR_RECORD)
  * class MyLLMTest {
+ *
+ *     @VCRModel
+ *     private EmbeddingModel embeddingModel;
+ *
+ *     @VCRModel
+ *     private ChatModel chatModel;
+ *
+ *     @BeforeEach
+ *     void setup() {
+ *         // Initialize models normally - VCR wraps them automatically
+ *         embeddingModel = new OpenAiEmbeddingModel(...);
+ *         chatModel = new OpenAiChatModel(...);
+ *     }
+ *
  *     @Test
  *     void testLLMCall() {
  *         // LLM calls are automatically recorded/replayed
+ *         embeddingModel.embed("Hello");
+ *         chatModel.generate("What is Redis?");
  *     }
  * }
  * }</pre>
@@ -39,6 +60,8 @@ public class VCRExtension
         AfterEachCallback,
         TestWatcher {
 
+  private static final Logger LOG = LoggerFactory.getLogger(VCRExtension.class);
+
   private static final ExtensionContext.Namespace NAMESPACE =
       ExtensionContext.Namespace.create(VCRExtension.class);
 
@@ -80,13 +103,97 @@ public void beforeEach(ExtensionContext extensionContext) throws Exception {
     // Check for method-level mode overrides
     var method = extensionContext.getRequiredTestMethod();
 
+    VCRMode effectiveMode;
     if (method.isAnnotationPresent(VCRDisabled.class)) {
-      context.setEffectiveMode(VCRMode.OFF);
+      effectiveMode = VCRMode.OFF;
     } else if (method.isAnnotationPresent(VCRRecord.class)) {
-      context.setEffectiveMode(VCRMode.RECORD);
+      effectiveMode = VCRMode.RECORD;
     } else {
       // Use class-level or default mode
-      context.setEffectiveMode(context.getConfiguredMode());
+      effectiveMode = context.getConfiguredMode();
+    }
+    context.setEffectiveMode(effectiveMode);
+
+    // Wrap @VCRModel annotated fields with cassette store
+    wrapAnnotatedFields(extensionContext, testId, effectiveMode, context.getCassetteStore());
+  }
+
+  /**
+   * Scans the test instance for fields annotated with {@code @VCRModel} and wraps them with VCR
+   * interceptors.
+   */
+  private void wrapAnnotatedFields(
+      ExtensionContext extensionContext,
+      String testId,
+      VCRMode mode,
+      VCRCassetteStore cassetteStore) {
+
+    if (mode == VCRMode.OFF) {
+      return; // Don't wrap if VCR is disabled
+    }
+
+    Object testInstance = extensionContext.getRequiredTestInstance();
+    Class<?> testClass = testInstance.getClass();
+
+    // Collect all fields including from parent classes
+    List<Field> allFields = new ArrayList<>();
+    Class<?> currentClass = testClass;
+    while (currentClass != null && currentClass != Object.class) {
+      for (Field field : currentClass.getDeclaredFields()) {
+        allFields.add(field);
+      }
+      currentClass = currentClass.getSuperclass();
+    }
+
+    // Also check fields from nested test classes
+    Class<?> enclosingClass = testClass.getEnclosingClass();
+    if (enclosingClass != null) {
+      // For nested classes, we need to access the outer instance
+      for (Field field : enclosingClass.getDeclaredFields()) {
+        if (field.isAnnotationPresent(VCRModel.class)) {
+          wrapFieldInEnclosingInstance(
+              testInstance, enclosingClass, field, testId, mode, cassetteStore);
+        }
+      }
+    }
+
+    // Wrap fields in the test instance
+    for (Field field : allFields) {
+      if (field.isAnnotationPresent(VCRModel.class)) {
+        VCRModel annotation = field.getAnnotation(VCRModel.class);
+        VCRModelWrapper.wrapField(
+            testInstance, field, testId, mode, annotation.modelName(), cassetteStore);
+      }
+    }
+  }
+
+  /** Wraps a field in the enclosing instance of a nested test class. */
+  @SuppressWarnings("java:S3011") // Reflection access is intentional
+  private void wrapFieldInEnclosingInstance(
+      Object nestedInstance,
+      Class<?> enclosingClass,
+      Field field,
+      String testId,
+      VCRMode mode,
+      VCRCassetteStore cassetteStore) {
+    try {
+      // Find the synthetic field that holds reference to the enclosing instance
+      for (Field syntheticField : nestedInstance.getClass().getDeclaredFields()) {
+        if (syntheticField.getName().startsWith("this$")
+            && syntheticField.getType().equals(enclosingClass)) {
+          syntheticField.setAccessible(true);
+          Object enclosingInstance = syntheticField.get(nestedInstance);
+
+          if (enclosingInstance != null) {
+            VCRModel annotation = field.getAnnotation(VCRModel.class);
+            VCRModelWrapper.wrapField(
+                enclosingInstance, field, testId, mode, annotation.modelName(), cassetteStore);
+          }
+          break;
+        }
+      }
+    } catch (IllegalAccessException e) {
+      LOG.warn("Failed to access enclosing instance: {}", e.getMessage());
     }
   }
 

core/src/main/java/com/redis/vl/test/vcr/VCRModel.java

@@ -0,0 +1,59 @@
+package com.redis.vl.test.vcr;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a field to be automatically wrapped with VCR recording/playback functionality.
+ *
+ * <p>When applied to an {@code EmbeddingModel} or {@code ChatModel} field, the VCR extension will
+ * automatically wrap the model with the appropriate VCR wrapper after it's initialized.
+ *
+ * <p>Usage:
+ *
+ * <pre>{@code
+ * @VCRTest(mode = VCRMode.PLAYBACK_OR_RECORD)
+ * class MyLLMTest {
+ *
+ *     @VCRModel
+ *     private EmbeddingModel embeddingModel;
+ *
+ *     @VCRModel
+ *     private ChatModel chatModel;
+ *
+ *     @BeforeEach
+ *     void setup() {
+ *         // Initialize your models normally - VCR will wrap them automatically
+ *         embeddingModel = new OpenAiEmbeddingModel(...);
+ *         chatModel = new OpenAiChatModel(...);
+ *     }
+ *
+ *     @Test
+ *     void testEmbedding() {
+ *         // Use the model - calls are recorded/replayed transparently
+ *         float[] embedding = embeddingModel.embed("Hello").content();
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p>Supported model types:
+ *
+ * <ul>
+ *   <li>LangChain4J: {@code dev.langchain4j.model.embedding.EmbeddingModel}, {@code
+ *       dev.langchain4j.model.chat.ChatLanguageModel}
+ *   <li>Spring AI: {@code org.springframework.ai.embedding.EmbeddingModel}, {@code
+ *       org.springframework.ai.chat.model.ChatModel}
+ * </ul>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
+public @interface VCRModel {
+
+  /**
+   * Optional model name for embedding cache key generation. If not specified, the field name will
+   * be used.
+   */
+  String modelName() default "";
+}