assert.Same() for map

[tturbs]

Original issue: #1691

Previously, assert.Same() checked whether two maps were the same instance (i.e., same memory address), but this no longer seems to be the case. As someone familiar with C, I might be biased toward thinking of maps as pointers. However, when using assert.Same() to verify if two maps share the same address, it returns false.

Suggestions:

1. Should assert.Same() treat maps like pointers (checking address equivalence), aligning with C-like behavior?
2. Alternatively, is a dedicated function (e.g., assert.SameMap()) needed to handle map comparisons explicitly?

I’d appreciate the community’s thoughts on this behavior and potential solutions.
Let me know if you’d like further refinements! 😊

[brackendawson]

History

Previously, assert.Same() checked whether two maps were the same instance (i.e., same memory address), but this no longer seems to be the case.

This has never been the case. There used to be a bug where Same would always pass and NotSame would always fail, regardless of what maps were compared. It happened because the error handling which checks both arguments are pointers was interpreted as an assertion result. This bug has been fixed by #1664 and Same and NotSame now correctly refuse to compare maps.

Trying to assert maps are the same or not the same

Now on to the topic at hand, how should one test that maps are the same or not the same? Firstly, same is an ambiguous term. What does "same" mean for a map?

Map structures only

An option is that either Same/NotSame or a new assertion is made to check that map values reference the same underlying map data structure or not.

This would have a danger where they could be different map data structures referencing the same underlying data in their keys and/or values. One use case for this I've seen is to confirm that a map has been cloned correctly, this assertion would not test this.

But as far as I know it is impossible to write this assertion in Go because you cannot get the address from a map value, even by reflection or unsafe. Please do prove me wrong with a compilable example.

Map keys and values

Another option says that a map is the same if all of its keys and values reference the same data when they are pointers. Remember we still cannot confirm that the map data structures are the same.

It's possible to confirm a true clone of a map has been made but only if the map key or value contains a pointer type. If any of those types are structs with un-exported fields then it is only possible to do this from your package and testify cannot do it for you. Here is an example:

package kata_test

import (
	"testing"

	"github.com/stretchr/testify/assert"
)

type nest struct {
	// i cannot be referenced by testify because it is unexported. It is only
	// possible to write assertMapsAreTrueClones if nest containst at least one
	// pointer field.
	i *int
}

func TestIfy(t *testing.T) {
	x, y := 1, 1
	a := map[string]nest{"one": {&x}}
	b := map[string]nest{"one": {&y}}

	assertMapsAreTrueClones(t, a, b)
}

func assertMapsAreTrueClones(t *testing.T, a, b map[string]nest) bool {
	t.Helper()
	if !assert.Equalf(t, a, b, "map values are not equal\na: %v\nb: %v", a, b) {
		return false
	}
	for k := range a {
		if a[k].i == b[k].i {
			t.Errorf("a[%#[1]v].i and b[%#[1]v].i are the same reference", k)
			return false
		}
	}
	return true
}

If the maps' keys and values contain no pointer types and all of the keys and values have the same value; then it is not possible to confirm whether they are or are not the same map. It is only possible to say it's a different map if some of the values are different, but this would be the Equal assertion, not the Same assertion.

Conclusion

Except in the case where a map's key or value has or is an exported pointer type; it is impossible for testify to assert that a map is NotSame.

It is always impossible to assert that maps are the Same.

If you don't agree with this, then please open a PR implementing any Same/NotSame behaviour for map values. I will either give you a testcase which proves the above, or I will happily concede.

[Michael0x2a]

Hmm, I'm a little confused by the argument made here.

Today, assert.Same/assert.NotSame does not promise to check whether its operands are full-fledged clones. It only promises to check if the two pointers refer to different objects.

For example, this test will pass even though the two Wrapper objects are not true clones:

type Wrapper struct {
	inner *int
}

func TestIsDifferentObject(t *testing.T) {
	shared := 123
	a := &Wrapper{inner: &shared}
	b := &Wrapper{inner: &shared}
	assert.NotSame(t, a, b)
}

So given assert.Same/assert.NotSame currently does not inspect the contents of structs, why is it important to do so for maps? It seems to me we should have the same standard for both types and either:

1. Stick to checking whether just the two values are referring to different objects regardless of if the objects are structs or maps. We leave leave checking the inner contents of both to the user.

   If necessary, we could also leave an warning in the docs making it clear assert.Same/assert.NotSame are not capable of verifying if two objects are true clones, and that the user must write their own value to recursively check the contents of their objects if they contain any pointers.

2. If users are routinely expecting assert.Same/assert.NotSame to be capable of verifying the operands are true clones, then rename or functions to make it more clear they are not capable of doing this. Once we do this, it should be be reasonable and no longer surprising to extend the renamed functions to support checking pointer-equality for things like maps.

   (Or, if we want to take an even harder line, deprecate and eventually remove the functions.)

Obviously, the third option is to do nothing and have Same/NotSame continue to support only literal pointers. It's for sure an improvement from before, when we produced bogus results for unsupported inputs. But it seems a bit of a shame to not extend them to check things that are de-facto pointers like maps.

Or is there something I'm misunderstanding?

[brackendawson]

I think your understanding is correct. We've spoken at length here about why we can't support the ideal version which can inspect maps the way people expect. The best way to understand why is probably to try to implement it, I'll even review your PR and give you a test-case that breaks your implementation if you want (or maybe you'll prove me wrong).

Option 2 would be nice but it's a breaking change, so sadly it's a no.

The best way we can improve the experience is to keep our documentation as good as it can get, pull requests welcome, currently it is:

Same asserts that two pointers reference the same object.

If we can statically identify any mis-use which testify will not warn about appropriately, then we might be able to make testifylint catch it.

[Michael0x2a]

Sure, here is a PR: #1777

We've spoken at length here about why we can't support the ideal version which can inspect maps the way people expect

I'm assuming that by "ideal version", you mean introspecting the contents of maps to compare their keys and values?

Personally, I would find it surprising if Same performed such a check -- users who want that behavior can use something like Equals instead. Instead, I think it would be more desirable + less surprising if it stuck to a shallow pointer equality check.

That is, it asserts the two objects refer to the same underlying entity. This simplifies the implementation, since it would mean a test case like a := makeSomeObjectOrMap(); b := clone(a); assert.Same(t, a, b) would fail, as desired. It would be extremely surprising to me if this test were to pass instead.

[brackendawson]

But as far as I know it is impossible to write this assertion in Go because you cannot get the address from a map value, even by reflection or unsafe. Please do prove me wrong with a compilable example.

I was wrong: #1777

reflect.Value.Pointer and reflect.Value.UnsafePointer both do it.

[breadnette]

Sorry, maybe I'm naïve and misunderstanding the problem, but what's wrong with e.g.

func assertMapsAreTrueClones(t *testing.T, a, b map[string]nest) bool {
	t.Helper()

	if !assert.NotNil(t, a, "two nil maps cannot be the same") {
		return false
	}
	if !assert.NotNil(t, b, "two nil maps cannot be the same") {
		return false
	}
	if !assert.Equalf(t, fmt.Sprintf("%p", a), fmt.Sprintf("%p", b), "a and b should have same pointer") {
		return false
	}
	return true
}

?

[brackendawson]

It doesn't work:

package main

import (
	"fmt"
	"testing"

	"github.com/stretchr/testify/assert"
)

func assertMapsAreTrueClones(t *testing.T, a, b map[string]*int) bool {
	t.Helper()

	if !assert.NotNil(t, a, "two nil maps cannot be the same") {
		return false
	}
	if !assert.NotNil(t, b, "two nil maps cannot be the same") {
		return false
	}
	if !assert.Equalf(t, fmt.Sprintf("%p", a), fmt.Sprintf("%p", b), "a and b should have same pointer") {
		return false
	}
	return true
}

func TestIfy(t *testing.T) {
	i := 1
	m1 := map[string]*int{"one": &i}
	m2 := make(map[string]*int)
	for k, v := range m1 {
		// a true clone must not reference the same values
		w := *v
		m2[k] = &w
	}
	assertMapsAreTrueClones(t, m1, m2)
}

[breadnette]

Apologies, I misunderstood where the example was going because it was late on friday. I was trying to address:

This would have a danger where they could be different map data structures referencing the same underlying data in their keys and/or values. One use case for this I've seen is to confirm that a map has been cloned correctly, this assertion would not test this.

But as far as I know it is impossible to write this assertion in Go because you cannot get the address from a map value, even by reflection or unsafe. Please do prove me wrong with a compilable example.

I was addressing that last part, but you're right that this is incomplete. I think there's a slight bug in the counterexample FWIW, in that the loop would need to be

for k, v := range m1 {
  m2[k] = &(*v)
}

as otherwise m2[k] = &w is making it reference that local variable and they end up not being the same pointer; however the &(*v) gives me a map where I'm able to mutate both with *(m1["one"]) = 2

Bearing in mind the request was a function that verifies the maps are clones, what about this?

// assertMapsAreTrueClones returns true if the maps are clones that don't reference the same underlying data
func assertMapsAreTrueClones[K comparable, V any](t *testing.T, a, b map[K]V) bool {
	t.Helper()

	if !assert.NotNil(t, a, "two nil maps cannot be the same") {
		return false
	}
	if !assert.NotNil(t, b, "two nil maps cannot be the same") {
		return false
	}

	if !assertMapsNotSamePointer(t, a, b) {
		return false
	}

	if !assert.Equal(t, len(a), len(b)) {
		return false
	}

	vIsPtr := reflect.ValueOf(*new(V)).Kind() == reflect.Ptr

	for k := range a {
		if !assert.Containsf(t, b, k, "b should contain all elements of a") {
			return false
		}

		if vIsPtr {
			if !assert.NotSamef(t, a[k], b[k], "a[%v] and b[%v] should not be same pointer", k, k) {
				return false
			}
		}

		if !assert.Equal(t, a[k], b[k], fmt.Sprintf("a[%v] and b[%v] should have equal values", k, k)) {
			return false
		}
	}

	return true
}

func assertMapsNotSamePointer[K comparable, V any](t *testing.T, a, b map[K]V) bool {
	t.Helper()

	if !assert.NotEqualf(t, fmt.Sprintf("%p", a), fmt.Sprintf("%p", b), "a and b should not have same pointer") {
		return false
	}

	return true
}

Now that test case fails as the data is the same pointer:

// TestIfy fails because the maps point to the same data
func TestIfy(t *testing.T) {
	i := 1
	m1 := map[string]*int{"one": &i}
	m2 := make(map[string]*int)
	for k, v := range m1 {
		// a true clone must not reference the same values
		m2[k] = &(*v)
	}
	assertMapsAreTrueClones(t, m1, m2)
}

Checking the equality to verify if the maps are clones or not though feels almost like an additional check to what I personally would expect Same/NotSame to do for a map, though. Since Same asserts that two pointers reference the same object. I would expect it just to check the map pointers (and the underlying pointers, as you pointed out) and just report if the pointers are the same; and then that testing if a map was a clone would be handled more like

assert.NotSame(t, a, b, "a and b shouldn't point to same map/underlying data")
assert.EqualValue(t, a, b, "b should have cloned values from a")

[breadnette]

Okay, I had a bit of time to try to take a look at this in the testify package and I think I see where the rub is -- i.e., that we don't have access to what I wrote, because all of the assertions are specifically written to take any. There's no way, then, to operate on map[K]V, and only reflection is possible.

We can still compare the map pointers themselves, but as far as I've gotten with a sameMap implementation, I get blocked on trying to ensure the maps aren't clones because reflect.Value.MapIndex automatically copies the Value to prevent accidentally changing the map data. That bit of protective code in reflect bars us access to the pointers; the same is true for MapRange. So writing this without generics requires functionality that the language authors seem to not want reflect to have.

I realize that probably 95% of the time, that behavior from reflect is useful for preventing bugs, but it's a bit unfortunate that it's the only functionality provided by reflect. Additionally, mapiternext seems to do this as well, meaning MapRange won't report the actual pointer addresses of elements.

So doing something like firstAddr, secondAddr := fmt.Sprintf("%p", first), fmt.Sprintf("%p", second) would allow comparing the map pointers themselves, but then every way that reflection gives us to iterate over a reflect.Value map does a clone of any values before giving access. Even just calling MapRange() on the same map twice, I can't get the original pointers.

Maybe there's an incredibly convoluted way, but I'm not sure what that would be.

[tturbs]

I understand and appreciate the correction regarding the behavior of assert.Equal() and the nature of nil versus empty slices in Go, as well as the point that Go maps do not expose their memory addresses in the same way as C.

However, I still believe there is a meaningful distinction to be made between deep equality and reference equality when working with maps. While assert.Equal() checks for deep equality and assert.Same() checks for pointer equality, there currently isn’t a clean way to assert that two maps reference the exact same underlying data structure (i.e., a reference copy vs. a deep copy).

This behavior is illustrated in the following code:

m := map[int]int{1: 1, 2: 2}
n := m
o := map[int]int{1: 1, 2: 2}

// Simulating Same vs Equal using pointer string formatting.
fmt.Printf("Same: %v\n", fmt.Sprintf("%p", m) == fmt.Sprintf("%p", n)) // Same: true
fmt.Printf("Equal: %v\n", fmt.Sprintf("%p", m) == fmt.Sprintf("%p", o)) // Equal: false

Instead of this kind of boilerplate, I believe it would be beneficial to have a dedicated assertion like:

assert.SameMap(t, m, n)
assert.NotSameMap(t, m, o)

Such a function would enhance clarity, reduce repetitive code, and express intent more directly—particularly when one needs to verify whether two variables point to the same map instance. This would align well with the principles of expressive testing and reduce the need for workarounds like comparing pointer strings.

[tturbs]

Hi @breadnette,
I wrote my comment before seeing your last reply. What you mentioned focuses on comparing the keys and values within a map, but I'm wondering—wouldn't it still be possible to compare the map references themselves? If two maps share the same reference, I believe it's reasonable to consider them the same.

[breadnette]

@tturbs

Comparing map pointers

What you mentioned focuses on comparing the keys and values within a map, but I'm wondering—wouldn't it still be possible to compare the map references themselves? If two maps share the same reference, I believe it's reasonable to consider them the same.

In the sense of SameMaps doing the pointer check a la:

func SameMap(t TestingT, expected, actual interface{}, msgAndArgs ...interface{}) bool {
	if h, ok := t.(tHelper); ok {
		h.Helper()
	}

	samePtr, ok := sameMaps(expected, actual)
	if !ok {
		return Fail(t, "Both arguments must be maps", msgAndArgs...)
	}

	if !samePtr {
		return Fail(t, "Maps point to different data" +
		"expected: %#[1]p %#[1]v\n"+
		"actual  : %#[2]p %#[2]v", expected, actual), msgAndArgs...)
	}

	return true
}

func sameMaps(first, second any) (samePtr bool, ok bool) {
	firstMap, secondMap := reflect.ValueOf(first), reflect.ValueOf(second)
	if firstMap.Kind() != reflect.Map || secondMap.Kind() != reflect.Map {
		return false, false
	}

	firstType, secondType := reflect.TypeOf(first), reflect.TypeOf(second)
	if firstType != secondType {
		return false, true
	}

	firstAddr, secondAddr := fmt.Sprintf("%p", first), fmt.Sprintf("%p", second)
	if firstAddr == secondAddr {
		return true, true
	}

	return false, true
}

Then yes, we can write a SameMaps func for that fairly trivially. I also personally agree that this would be reasonable behavior for it, but I'll come back to that.

Playing devil's advocate, where this breaks down for me is @brackendawson's earlier point:

Now on to the topic at hand, how should one test that maps are the same or not the same? Firstly, same is an ambiguous term. What does "same" mean for a map?

Now, with this SameMap implementation,

m := map[int]int{1: 1, 2: 2}
n := m // Same

That copied map is the same. But what about a map of pointers? To quote Bracken again:

This would have a danger where they could be different map data structures referencing the same underlying data in their keys and/or values.

Are these maps the same? :

func ptr [V any] (v V) *V { return &v }

// . . .
m := map[int]*int{1: ptr(1), 2: ptr(2)}
n := make(map[int]*int, len(m))
for k := range m {
	v := m[k]
	n[k] = v
}

They wouldn't pass Same as written above, but they're not... exactly not the same:

fmt.Printf("Same: %v\n", fmt.Sprintf("%p", m) == fmt.Sprintf("%p", n)) // Same: false
for k := range m {
	fmt.Printf("m[k]:%v\tn[k]:%v\n", m[k], n[k])
	fmt.Printf("Same: %v\n", fmt.Sprintf("%p", m[k]) == fmt.Sprintf("%p", n[k])) // Same: true
}
fmt.Printf("m:%+v\tn:%+v\n", m, n)

fmt.Printf("*m[1]:%+v\t*n[1]:%+v\n", *m[1], *n[1]) // *m[1]:1	*n[1]:1
n[1] = ptr(4) // this changes only n
fmt.Printf("*m[1]:%+v\t*n[1]:%+v\n", *m[1], *n[1]) // *m[1]:1	*n[1]:4

fmt.Printf("*m[2]:%+v\t*n[2]:%+v\n", *m[2], *n[2]) // *m[2]:2	*n[2]:2
*n[2] = 3 // this changes both n and m
fmt.Printf("*m[2]:%+v\t*n[2]:%+v\n", *m[2], *n[2]) // *m[2]:3	*n[2]:3

So, to Bracken's point:

This would have a danger where they could be different map data structures referencing the same underlying data in their keys and/or values. One use case for this I've seen is to confirm that a map has been cloned correctly, this assertion would not test this.

This is entirely right. I'm ambivalent to it -- I personally agree that checking the pointer address of the map itself should be the be the defined behavior of Same for maps / SameMap. I feel that this is consistent with the way that testify currently works:

type myNestedStruct struct {
	i *int
}
i := 1
s1 := myNestedStruct{i: &i}
s2 := myNestedStruct{i: s1.i} // same pointer
s3 := myNestedStruct{i: &i}   // another pointer to same object
assert.Same(t, s1.i, s2.i)           // true
assert.Same(t, s1.i, s3.i)           // true
assert.NotSame(t, &s1, &s2)          // true
assert.NotSame(t, &s1, &s3)          // true
assert.Equal(t, s1, s2)              // true
assert.Equal(t, s1, s3)              // true
*s3.i = 2
assert.Equal(t, 2, *s2.i) // true

So when you have a type that contains pointers, already you need to understand to check your inner pointers properly as doing assertions on their containing structs won't flag them as the Same either.

---

So what about the case when map values are pointers?

Now, if we for the sake of argument accept that the Same func must compare the values to ensure there aren't same pointers, we do in fact run into the problem Bracken mentioned:

But as far as I know it is impossible to write this assertion in Go because you cannot get the address from a map value, even by reflection or unsafe. Please do prove me wrong with a compilable example.

My earlier example was easy to write thanks to using the generic map[K]V. Testify's functions are written to take interface{}, and there's no [exported] way (that I'm aware of) to convert any into a generic type parameter, as Go wants to satisfy generic type constraints at compile time. So when we're stuck operating on any... there really just isn't any way to get the references to the map values. Every method of accessing the map values via reflection copies the value always (here's an example). I had tried playing with numerous things to try to get around that, but that's just a wall in the reflect package.

To be honest, this feels to me like one of the places where the language developers made an opinionated decision to remove a footgun and in the process made it impossible to do what we technically have a very valid reason to want to do here for the purpose of testing. Frankly, if a developer is in the weeds of using reflect and unsafe pointers to interact with a map... they probably at least know at that point that they need to be careful, so I don't necessarily agree with the language author's decision to make the map's pointers entirely inaccessible. There may be a feature that could do in exchange for being added to the "hall of shame" 😏 by referencing some internal language funcs via linkname... I don't know enough about Go atm to know what options are provided there, but clearly the language authors disapprove of it, so I'm not rushing to try to open a PR for someone else's repo that uses it, ha.

If it is the case that in fact we do need same to do pointer checks on all the map values... well, here's where I had gotten to with trying to get something working with reflection and watching things in the debugger. I did make a fair effort haha. Apologies if anything is in a funky state since I had been trying a few different things working through the map iterators.

// SameMap asserts that two maps point to the same map object, or all their keys point to the same underlying data.
//
//	assert.SameMap(t, m1, m2)
//
// Both arguments must be map variables.
func SameMap(t TestingT, expected, actual interface{}, msgAndArgs ...interface{}) bool {
	if h, ok := t.(tHelper); ok {
		h.Helper()
	}

	samePtr, ok, samePtrKeys := sameMaps(expected, actual)
	if !ok {
		return Fail(t, "Both arguments must be maps", msgAndArgs...)
	}

	if samePtr {
		// both maps point to same map object
		return true
	}

	// we know this is a map because ok is true, so this is safe
	mapLen := reflect.ValueOf(expected).Len()

	if len(samePtrKeys) != mapLen {
		return Fail(t, fmt.Sprintf("Not all indexes point to same data:\n"+
			"expected: %#[1]p %#[1]v\n"+
			"actual  : %#[2]p %#[2]v", expected, actual), msgAndArgs...)
	}

	return true
}

// NotSameMap asserts that two maps don't reference the same object, and don't point to some of the same data.
//
//	assert.NotSameMap(t, m1, m2)
//
// Both arguments must be map variables.
func NotSameMap(t TestingT, expected, actual interface{}, msgAndArgs ...interface{}) bool {
	if h, ok := t.(tHelper); ok {
		h.Helper()
	}

	samePtr, ok, samePtrKeys := sameMaps(expected, actual)
	if !ok {
		return Fail(t, "Both arguments must be maps", msgAndArgs...)
	}

	if samePtr {
		// both maps point to same map object
		return Fail(t, fmt.Sprintf("Maps point to same address: \n"+
			"expected: %#[1]p %#[1]v\n"+
			"actual  : %#[2]p %#[2]v", expected, actual), msgAndArgs...)
	}

	if len(samePtrKeys) > 0 {
		return Fail(t, fmt.Sprintf("Indexes point to same data at keys: %+v", samePtrKeys))
	}

	return true
}

// sameMaps checks if two generic interface objects are pointers of the same
// type pointing to the same map, or are maps containing pointers to the same
// addresses. It returns three values: same indicating if they are the same type
// and point to the same object, ok indicating that both inputs are maps, and idxs
// indicating which key(s) point to the same data.
func sameMaps(first, second any) (samePtr bool, ok bool, samePtrKeys []any) {
	firstMap, secondMap := reflect.ValueOf(first), reflect.ValueOf(second)
	if firstMap.Kind() != reflect.Map || secondMap.Kind() != reflect.Map {
		return false, false, nil //not both are map
	}

	firstType, secondType := reflect.TypeOf(first), reflect.TypeOf(second)
	if firstType != secondType {
		return false, true, nil // both are maps, but of different types
	}

	firstAddr, secondAddr := fmt.Sprintf("%p", first), fmt.Sprintf("%p", second)
	if firstAddr == secondAddr {
		return true, true, nil // maps point to same underlying map
	}

	valueFromMapIter := func(iter *reflect.MapIter) reflect.Value {
		//mv := reflect.ValueOf(iter).Elem().FieldByName("m")
		//mp := reflect.NewAt(mv.Type(), unsafe.Pointer(mv.UnsafeAddr()))

		hv := reflect.ValueOf(iter).Elem().FieldByName("hiter")
		ha := reflect.NewAt(hv.Type(), unsafe.Pointer(hv.UnsafeAddr()))

		ev := ha.Elem().FieldByName("elem")
		evp := unsafe.Pointer(ev.UnsafeAddr())
		e := reflect.NewAt(ev.Type(), evp)

		fmt.Printf("%v, %v, %T\n", ev, evp, e.Elem())
		//mp := reflect.NewAt(mv.Type(), unsafe.Pointer(mv.UnsafeAddr()))
		return e
	}

	// iterate through the maps to compare; for each map key, we want to ensure both maps don't point to same address
	firstMapIter := firstMap.MapRange()
	for firstMapIter.Next() {
		fk := firstMapIter.Key()
		fmt.Printf("first: %v\n", fk.Interface())
		// we can't call Value because that copies the value and won't compare pointers. So we have to be naughty.
		fV := valueFromMapIter(firstMapIter)
		k := fV.Kind()
		if k != reflect.Ptr {
			// this map value is not a pointer, no need to check if second map has the same pointer
			continue
		}

		// our value is a pointer, so we need to see if other map at this key is the same pointer;
		// MapIter is in a random order, and trying to call MapIndex returns copy-by-value,
		// so we have to fully iterate through the second map
		secondMapIter := firstMap.MapRange()
		for secondMapIter.Next() {
			sk := secondMapIter.Key()
			fmt.Printf("second: %v\n", sk.Interface())
			if fk.Interface() != sk.Interface() {
				continue // not the same key
			}
			sV := valueFromMapIter(secondMapIter)
			if sV.Kind() == reflect.Ptr {
				fvType, svType := reflect.TypeOf(fV.Elem()), reflect.TypeOf(sV.Elem())
				if fvType == svType && fV.Interface() == sV.Interface() {
					samePtrKeys = append(samePtrKeys, fk.Interface())
				}
			}
			break // no need to continue iterating second map, we've already matched on the key
		}
	}
	if len(samePtrKeys) > 0 {
		return false, true, samePtrKeys
	}
	return false, true, nil
}

func Test_sameMap(t *testing.T) {
	type args struct {
		first  interface{}
		second interface{}
	}
	tests := []struct {
		name       string
		args       args
		expectKeys []any
		same       BoolAssertionFunc
		ok         BoolAssertionFunc
	}{
		{
			name: "maps pointing to same address should be same pointer",
			args: func() args {
				m1 := map[string]int{"foo": 2}
				m2 := m1
				return args{m1, m2}
			}(),
			same: True,
			ok:   True,
		},
		{	// fails:
			name: "maps pointing to same underlying values should return their same keys",
			args: func() args {
				m1 := map[string]*int{
					"foo": ptr(2),
					"bar": ptr(1),
				}
				m2 := make(map[string]*int, len(m1))
				for k, v := range m1 {
					m2[k] = v
				}
				return args{m1, m2}
			}(),
			same:       False,
			ok:         True,
			expectKeys: []any{"foo", "bar"},
		},
		{	// fails:
			name: "maps pointing to some of same underlying values should return their same keys",
			args: func() args {
				m1 := map[string]*int{
					"foo": ptr(2),
					"bar": ptr(1),
				}
				m2 := make(map[string]*int, len(m1))
				m2["foo"] = m1["foo"]
				barV := *m1["bar"] // clone m1[bar]
				m2["bar"] = &barV
				return args{m1, m2}
			}(),
			same:       False,
			ok:         True,
			expectKeys: []any{"foo"},
		},
		{
			name: "map[string]int != map[string]float32",
			args: args{first: map[string]int{"foo": 1}, second: map[string]float32{"foo": 1}},
			same: False,
			ok:   True,
		},
		{
			name: "map vs array (not map)",
			args: args{first: map[string]int{"foo": 1}, second: []int{1}},
			same: False,
			ok:   False,
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			same, ok, sameKeyPtrs := sameMaps(tt.args.first, tt.args.second)
			tt.same(t, same)
			tt.ok(t, ok)
			EqualValues(t, tt.expectKeys, sameKeyPtrs)
		})
	}
}

[tturbs]

I realize now that I was focused too much on convenience and overlooked some important aspects. Thanks to the thorough explanations from @breadnette and @brackendawson, I understand why functions like SameMap are inherently incomplete. It seems this discussion has reached a conclusion, so I will close it here. Thank you again for your insights and help.