Proposal

Create the following conventions for matcher prefixes:

1. Partial matchers. Example: isPerson(name: 'Loic').

   A partial matcher only matches the properties you provide. The matcher's arguments are null by default.

   You cannot use a partial matcher to assert a value is null. For example, I cannot check that a person's nickname is null using: isPerson(name: 'Loic', nickname: null). Instead, you need to use:

expect(person, isPerson(name: 'Loic'));
expect(person.nickname, isNull);

2. Exact matchers. Example: matchesPerson(name: 'Loic', nickname: null).

   An exact matcher matches all the values, including those you omit. The matcher's arguments have the same default value as the object's default value.

   The exact matcher is often less convenient than the partial matcher. To match an object with 20 non-default property values, you'll need to provide all 20 values to the exact matcher.

Migration

To adopt this naming convention, we'll want to:

1. Codify this to our style guide
2. Deprecate containsSemantics in favor of a new isSemantics matcher. (For history behind containsSemantics, see: Allow matchesSemantics to only match certain properties #107859)

cc @chunhtai