jnicklas/capybara — pull request #1235 by abotalov (2014-02-02 11:47:45+00:00)
Title: New API for working with windows (switching/finding/closing/opening/etc....)

I'd like to outline some points:

1. Previously Jonas proposed `use_window` as the name for `switch_to_window`. I named it `switch_to_window` as this name is more similar to Webdriver users.
2. I made `Window#exists?` as non-waiting as I don't see benefit to wait for window to become exist. `Window#closed?` is made non-waiting as `Window#exists?` is non-waiting.
3. This pull request deprecates support for passing strings to `within_window`. Reasons are:
1. To make API more synchronous (added methods operate only with instances of `Window` class, not strings).
2. Current implementation leads to impossibility of selecting window in some circumstances.
Example:
First window has url "http://www.example.com/2".
Second window has url "http://www.example.com/".
So `within_window('http://www.example.com/')` would select first window as it searches using `include?`. I think this behavior is surprising at least.
Other examples (e.g. for title) can be thinked out too so I think it's better to deprecate ability to pass strings to this method.
4. [Webriver wire protocol](https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/window/:windowHandle/size) and [Webdriver W3C spec](http://www.w3.org/TR/webdriver/#resizing-and-positioning-windows) have commands for resizing/getting size of not current window.
But [Webdriver itself doesn't support it](https://code.google.com/p/selenium/issues/detail?id=6472) and won't support in near future. So I decided that methods at driver level should be

```ruby
current_window_size
resize_current_window_to(width, height)
```
instead of
```ruby
window_size(handle)
resize_window_to(handle, width, height)
```
5. I implemented finding window by `switch_to_window`, `within_window` themselves instead of writing `find_window` method to prevent unnecessary additional switching of windows.
Here's how `find_window` would look like:

```ruby
window = find_window { page.title == 'Page title' }
within_window(window) { do_something }
```
But this swicthing back in `find_window` and force in `within_window` would be unnecessary operations. So I decided to implement finding directly in `switch_to_window` and `within_window`.
Note: switching to window takes ~20ms in Selenium.