How to locate windows is pretty complicated and not very well documented. There are also lot of undocumented and untested features. This issue covers cleaning up the functionality and, very importantly, documenting it adequately.

As part of the cleanup, undocumented features that are not considered useful are deprecated or removed. Such changes are obviously backwards incompatible, but because these are undocumented features, it's very unlikely that they are used widely. This is the functionality that is going to change:

• Using Python None or string null or empty string as a locator to select the main window is deprecated. Use documented main (default) instead.
• Using popup to select the latest new window is deprecated. Use documented new instead.
• Using self to select the current window is deprecated. Use earlier undocumented but much more explicit current instead.
• Locating windows by name, title or URL is not case-insensitive anymore.
• Specifying explicit locator strategy is not case-insensitive anymore.

There area also some enhancements:

• New keyword Get Window Handles is added to replace List Windows later. The old keyword is "silently deprecated" at this point.
• Explicit locator strategy can be specified using strategy:value syntax in addition to strategy=value (see also New strategy:value syntax to specify locator strategy in addition to current strategy=value #908).