cc: @bartekpacia

Here's the PR that cleans up the Finder API (as well as pulled out a generic base class for it.

Turns out the toString issue had a reason, there isn't a way to do custom formatting of the Actual part of the expect call without using toString, but I did add a parameter to the toString method to be able to actually describe just the finder itself, and the results are where that description is created.

nit: looks like the analyzer is unhappy about a space somewhere...

About the deprecations: I am very much against introducing replacement APIs without deprecating the old ones - even if this state is just intended to last a short period of time. Having two sets of APIs without clear marking which one is supposed to be used is creating user confusion, we have seen this before. Furthermore, if we delay the deprecation we may realize too late that for one reason or another we cannot actually deprecate the old API and then we are stuck with both. Also, even when the intention is to follow up with the deprecations right away, intentions and plans change and then things get forgotten. I just recently fixed a "TODO: deprecate this" four years after the reason to deprecate it became true and had to do a bunch of extra clean-up because people continued to use the not-yet-deprecated property in their code since they had no better way of knowing that they weren't supposed to.

I agree that it may not be practical to do all of these deprecations in this PR. For that, we have options. Some examples:

1. When it comes to renaming things, we can do the rename deprecation first (e.g. rename Finder to WidgetFinder, add a deprecated typedef) in a separate PR upfront.
2. We can chose to not introduce a replacement API at all (e.g. decide that Finder is a fine name and not introduce WidgetFinder).
3. We can chose to delay introducing the replacement to a future point in time (e.g. keep Finder for now and then in a follow-up rename it to WidgetFinder, we just need to accept that that may never happen, but we will not end up in a two APIs state).
4. ...

When it comes to deprecating a thing, we also need to evaluate whether the deprecation is worth it. We don't want to create too much churn for our developers without clear benefit for them. Right now, we enjoy there good will and they let use evolve the APIs to make them better. But if we - in their eyes - abuse that good will, people may become grumpy and less receptive to these kind of deprecations.

To evaluate whether a depreciation is worthwhile, we should collect some data. For each deprecation it would be worthwhile to collect:

1. How many lines of code need to be migrated in our own repository? In google3? For out customer tests, including the packages repository?
2. Can these deprecations be auto-migrated by dart fix?
3. How would one migrate to the new APIs?
4. What is the developer facing benefit for doing these migrations?

The last 3 points are what one would typically also cover in a migration guide. It is a good exercise to write this before doing the deprecations to make sure we have good reasons for it - and to illustrate that doing this is worthwhile.

Lastly, some concrete thoughts on some of the deprecations proposed:

• Finder -> WidgetFinder seems to have a rather low return on investment. Sure, we should have used that name from the beginning. If almost nobody is affected by this rename we can still do it, but if it affects hundreds of callsides outside of our direct control I would lean away from it.

• Finder.evaluate is called almost 3,000 times in google3. That's a lot of code that needs to be migrated. I am wondering if we instead should save everyone the trouble and design the new capabilities around this exiting API.

There's also some more guidance around this in our wiki: https://github.com/flutter/flutter/wiki/Tree-hygiene#handling-breaking-changes