From 8b2ba41c6c15a801db17f9c9d2bd91b499ce960b Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Sun, 12 Oct 2025 14:32:28 +1100
Subject: [PATCH] Improving first op test

---
 pkg/yqlib/doc/operators/first.md         | 23 ++++++++++++++++++-----
 pkg/yqlib/doc/operators/headers/first.md |  5 +++++
 pkg/yqlib/operator_first_test.go         | 18 +++++++++---------
 3 files changed, 32 insertions(+), 14 deletions(-)
 create mode 100644 pkg/yqlib/doc/operators/headers/first.md

diff --git a/pkg/yqlib/doc/operators/first.md b/pkg/yqlib/doc/operators/first.md
index 349fe1b0..ae0bd715 100644
--- a/pkg/yqlib/doc/operators/first.md
+++ b/pkg/yqlib/doc/operators/first.md
@@ -1,3 +1,8 @@
+# First
+
+Returns the first matching element in an array, or first matching value in a map.
+
+Can be given an expression to match with, otherwise will just return the first.
 
 ## First matching element from array
 Given a sample.yml file of:
@@ -20,8 +25,10 @@ Given a sample.yml file of:
 ```yaml
 - a: banana
 - a: cat
+  b: firstCat
 - a: apple
 - a: cat
+  b: secondCat
 ```
 then
 ```bash
@@ -30,6 +37,7 @@ yq 'first(.a == "cat")' sample.yml
 will output
 ```yaml
 a: cat
+b: firstCat
 ```
 
 ## First matching element from array with numeric condition
@@ -38,6 +46,7 @@ Given a sample.yml file of:
 - a: 10
 - a: 100
 - a: 1
+- a: 101
 ```
 then
 ```bash
@@ -53,7 +62,10 @@ Given a sample.yml file of:
 ```yaml
 - a: false
 - a: true
+  b: firstTrue
 - a: false
+- a: true
+  b: secondTrue
 ```
 then
 ```bash
@@ -62,6 +74,7 @@ yq 'first(.a == true)' sample.yml
 will output
 ```yaml
 a: true
+b: firstTrue
 ```
 
 ## First matching element from array with null values
@@ -84,19 +97,19 @@ a: cat
 Given a sample.yml file of:
 ```yaml
 - a: dog
-  b: 5
+  b: 7
 - a: cat
   b: 3
 - a: apple
-  b: 7
+  b: 5
 ```
 then
 ```bash
-yq 'first(.b > 4)' sample.yml
+yq 'first(.b > 4 and .b < 6)' sample.yml
 ```
 will output
 ```yaml
-a: dog
+a: apple
 b: 5
 ```
 
@@ -127,7 +140,7 @@ x:
 y:
   a: 100
 z:
-  a: 1
+  a: 101
 ```
 then
 ```bash
diff --git a/pkg/yqlib/doc/operators/headers/first.md b/pkg/yqlib/doc/operators/headers/first.md
new file mode 100644
index 00000000..c3afc64b
--- /dev/null
+++ b/pkg/yqlib/doc/operators/headers/first.md
@@ -0,0 +1,5 @@
+# First
+
+Returns the first matching element in an array, or first matching value in a map.
+
+Can be given an expression to match with, otherwise will just return the first.
diff --git a/pkg/yqlib/operator_first_test.go b/pkg/yqlib/operator_first_test.go
index 44ad9c0e..a83af4f6 100644
--- a/pkg/yqlib/operator_first_test.go
+++ b/pkg/yqlib/operator_first_test.go
@@ -13,15 +13,15 @@ var firstOperatorScenarios = []expressionScenario{
 	},
 	{
 		description: "First matching element from array with multiple matches",
-		document:    "[{a: banana},{a: cat},{a: apple},{a: cat}]",
+		document:    "[{a: banana},{a: cat, b: firstCat},{a: apple},{a: cat, b: secondCat}]",
 		expression:  `first(.a == "cat")`,
 		expected: []string{
-			"D0, P[1], (!!map)::{a: cat}\n",
+			"D0, P[1], (!!map)::{a: cat, b: firstCat}\n",
 		},
 	},
 	{
 		description: "First matching element from array with numeric condition",
-		document:    "[{a: 10},{a: 100},{a: 1}]",
+		document:    "[{a: 10},{a: 100},{a: 1},{a: 101}]",
 		expression:  `first(.a > 50)`,
 		expected: []string{
 			"D0, P[1], (!!map)::{a: 100}\n",
@@ -29,10 +29,10 @@ var firstOperatorScenarios = []expressionScenario{
 	},
 	{
 		description: "First matching element from array with boolean condition",
-		document:    "[{a: false},{a: true},{a: false}]",
+		document:    "[{a: false},{a: true, b: firstTrue},{a: false}, {a: true, b: secondTrue}]",
 		expression:  `first(.a == true)`,
 		expected: []string{
-			"D0, P[1], (!!map)::{a: true}\n",
+			"D0, P[1], (!!map)::{a: true, b: firstTrue}\n",
 		},
 	},
 	{
@@ -45,10 +45,10 @@ var firstOperatorScenarios = []expressionScenario{
 	},
 	{
 		description: "First matching element from array with complex condition",
-		document:    "[{a: dog, b: 5},{a: cat, b: 3},{a: apple, b: 7}]",
-		expression:  `first(.b > 4)`,
+		document:    "[{a: dog, b: 7},{a: cat, b: 3},{a: apple, b: 5}]",
+		expression:  `first(.b > 4 and .b < 6)`,
 		expected: []string{
-			"D0, P[0], (!!map)::{a: dog, b: 5}\n",
+			"D0, P[2], (!!map)::{a: apple, b: 5}\n",
 		},
 	},
 	{
@@ -61,7 +61,7 @@ var firstOperatorScenarios = []expressionScenario{
 	},
 	{
 		description: "First matching element from map with numeric condition",
-		document:    "x: {a: 10}\ny: {a: 100}\nz: {a: 1}",
+		document:    "x: {a: 10}\ny: {a: 100}\nz: {a: 101}",
 		expression:  `first(.a > 50)`,
 		expected: []string{
 			"D0, P[y], (!!map)::{a: 100}\n",