fix: Discover and document the contains/unordered tradeoff

Author: kinbiko

array.go

@@ -82,9 +82,7 @@ func (a *Asserter) checkArrayOrdered(path string, act, exp []interface{}) {
 func (a *Asserter) checkContainsArray(path string, act, exp []interface{}) {
 	a.tt.Helper()
 
-	var unordered bool
 	if len(exp) > 0 && exp[0] == "<<UNORDERED>>" {
-		unordered = true
 		exp = exp[1:]
 	}
 
@@ -95,13 +93,7 @@ func (a *Asserter) checkContainsArray(path string, act, exp []interface{}) {
 		return
 	}
 
-	if unordered {
-		a.checkContainsUnorderedArray(path, act, exp)
-		return
-	}
-	for i := range exp {
-		a.pathContainsf(fmt.Sprintf("%s[%d]", path, i), serialize(act[i]), serialize(exp[i]))
-	}
+	a.checkContainsUnorderedArray(path, act, exp)
 }
 
 func (a *Asserter) checkContainsUnorderedArray(path string, act, exp []interface{}) {
@@ -113,9 +105,7 @@ func (a *Asserter) checkContainsUnorderedArray(path string, act, exp []interface
 			ap := arrayPrinter{}
 			serializedAct := serialize(act[j])
 			New(&ap).pathContainsf("", serializedAct, serializedExp)
-			if len(ap) == 0 {
-				found = true
-			}
+			found = found || len(ap) == 0
 		}
 		if !found {
 			mismatchedExpPaths[fmt.Sprintf("%s[%d]", path, i+1)] = serializedExp // + 1 because 0th element is "<<UNORDERED>>"

integration_test.go

@@ -492,19 +492,28 @@ not found in
 ["alpha","beta","gamma"]`,
 		}},
 		"multi-element array contains itself": {`["alpha", "beta"]`, `["alpha", "beta"]`, nil},
-		"multi-element array does not contain itself permuted": {`["alpha", "beta"]`, `["beta" ,"alpha"]`, []string{
-			"expected string at '$[0]' to be 'beta' but was 'alpha'",
-			"expected string at '$[1]' to be 'alpha' but was 'beta'",
-		}},
+		// NOTE: There's an important design decision to be made here.
+		// Currently, in the case of "Containsf" there's an implicit "<<UNORDERED>>" (if it's explicitly written it will be ignored)
+		// This is so that nested arrays don't have to repeatedly say "<<UNORDERED">> assuming the user just wants to check for the existence of some element of an array.
+		// However, this makes jsonassert useless for cases where you want to partially assert that an ordered array exists.
+		// Ideally this package should be able to support both nicely.
+		"multi-element array does contain itself permuted": {`["alpha", "beta"]`, `["beta" ,"alpha"]`, []string{}},
 		// Allow users to test against a subset of the payload without erroring out.
 		// This is to avoid the frustraion and unintuitive solution of adding "<<UNORDERED>>" in order to "enable" subsetting,
 		// which is really implied with the `contains` part of the API name.
-		"multi-element array does contain its subset":                      {`["alpha", "beta"]`, `["alpha"]`, []string{}},
+		"multi-element array does contain its subset":                      {`["alpha", "beta"]`, `["beta"]`, []string{}},
 		"multi-element array does not contain its superset":                {`["alpha", "beta"]`, `["alpha", "beta", "gamma"]`, []string{"length of expected array at '$' was longer (length 3) than the actual array (length 2)", `actual JSON at '$' was: ["alpha","beta"], but expected JSON to contain: ["alpha","beta","gamma"]`}},
 		"expected and actual have different types":                         {`{"foo": "bar"}`, `null`, []string{"actual JSON (object) and expected JSON (null) were of different types at '$'"}},
 		"expected any value but got null":                                  {`{"foo": null}`, `{"foo": "<<PRESENCE>>"}`, []string{"expected the presence of any value at '$.foo', but was absent"}},
 		"unordered multi-element array of different types contains subset": {`["alpha", 5, false, ["foo"], {"bar": "baz"}]`, `["<<UNORDERED>>", 5, "alpha", {"bar": "baz"}]`, nil},
 		"object contains its subset":                                       {`{"foo": "bar", "alpha": "omega"}`, `{"alpha": "omega"}`, nil},
+		/*
+			"array inside object": {
+				`{ "arr": [                  { "fork": { "start": "stop" }, "nested": ["really",        "fast"] } ] }`,
+				`{ "arr": [ "<<UNORDERED>>", { "fork": { "start": "stop" }, "nested": ["<<UNORDERED>>", "fast"] } ] }`,
+				nil,
+			},
+		*/
 	}
 	for name, tc := range tt {
 		tc := tc