fix(meta): Add OverrideStrategy enum for the fakeable trait to support merge/replace (#646)

* Add `OverrideStrategy` enum and enable merge/replace options for faking responses, updating `Fakeable::fake()` and its attribute builder accordingly.

* Fix and add a test for the OverrideStrategy in `Fakeable::fake()` implementation.

fixes: #581

Author: droath

src/Testing/Enums/OverrideStrategy.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Testing\Enums;
+
+enum OverrideStrategy: string
+{
+    case Merge = 'merge';
+    case Replace = 'replace';
+}

src/Testing/Responses/Concerns/Fakeable.php

@@ -5,44 +5,26 @@
 namespace OpenAI\Testing\Responses\Concerns;
 
 use OpenAI\Responses\Meta\MetaInformation;
+use OpenAI\Testing\Enums\OverrideStrategy;
 
 trait Fakeable
 {
     /**
      * @param  array<string, mixed>  $override
      */
-    public static function fake(array $override = [], ?MetaInformation $meta = null): static
-    {
+    public static function fake(
+        array $override = [],
+        ?MetaInformation $meta = null,
+        OverrideStrategy $strategy = OverrideStrategy::Merge,
+    ): static {
         $class = str_replace('OpenAI\\Responses\\', 'OpenAI\\Testing\\Responses\\Fixtures\\', static::class).'Fixture';
 
         return static::from(
-            self::buildAttributes($class::ATTRIBUTES, $override),
+            self::buildAttributes($class::ATTRIBUTES, $override, $strategy),
             $meta ?? self::fakeResponseMetaInformation(),
         );
     }
 
-    /**
-     * @return mixed[]
-     */
-    private static function buildAttributes(array $original, array $override): array
-    {
-        $new = [];
-
-        foreach ($original as $key => $entry) {
-            $new[$key] = is_array($entry)
-                ? self::buildAttributes($entry, $override[$key] ?? [])
-                : $override[$key] ?? $entry;
-            unset($override[$key]);
-        }
-
-        // we are going to append all remaining overrides
-        foreach ($override as $key => $value) {
-            $new[$key] = $value;
-        }
-
-        return $new;
-    }
-
     public static function fakeResponseMetaInformation(): MetaInformation
     {
         return MetaInformation::from([
@@ -59,4 +41,15 @@ public static function fakeResponseMetaInformation(): MetaInformation
             'x-request-id' => ['3813fa4fa3f17bdf0d7654f0f49ebab4'],
         ]);
     }
+
+    private static function buildAttributes(
+        array $original,
+        array $override,
+        OverrideStrategy $strategy = OverrideStrategy::Merge): array
+    {
+        return match ($strategy) {
+            OverrideStrategy::Replace => array_replace($original, $override),
+            OverrideStrategy::Merge => array_replace_recursive($original, $override),
+        };
+    }
 }

tests/Responses/Responses/CreateResponse.php

@@ -5,6 +5,7 @@
 use OpenAI\Responses\Responses\CreateResponseFormat;
 use OpenAI\Responses\Responses\CreateResponseReasoning;
 use OpenAI\Responses\Responses\CreateResponseUsage;
+use OpenAI\Testing\Enums\OverrideStrategy;
 
 test('from', function () {
     $response = CreateResponse::from(createResponseResource(), meta());
@@ -76,6 +77,42 @@
         ->id->toBe('resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c');
 });
 
+test('fake with the "replace" and "merge" strategy override', function () {
+    $attributes = [
+        'output' => [
+            [
+                'id' => 'msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b',
+                'role' => 'assistant',
+                'type' => 'message',
+                'status' => 'completed',
+                'content' => [
+                    [
+                        'type' => 'output_text',
+                        'text' => 'This is the fake test output',
+                        'annotations' => [],
+                    ],
+                ],
+            ],
+        ],
+    ];
+    $response = CreateResponse::fake(
+        $attributes,
+        strategy: OverrideStrategy::Replace
+    );
+
+    expect($response)
+        ->output->toBeArray()->toHaveCount(1)
+        ->outputText->toBe('This is the fake test output');
+
+    $response = CreateResponse::fake(
+        $attributes,
+    );
+
+    expect($response)
+        ->output->toBeArray()->toHaveCount(2)
+        ->outputText->toBe('This is the fake test output As of today, March 9, 2025, one notable positive news story...');
+});
+
 test('fake with override', function () {
     $response = CreateResponse::fake([
         'id' => 'resp_1234',