Skip to content

Commit d5b9395

Browse files
diemoldiemol
authored
Merge branch 'dev' into installing_lib
2 parents 6596550 + cfda4d0 commit d5b9395

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+2173
-2348
lines changed

‎.github/ISSUE_TEMPLATE/translation_request.yml

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: 🇧🇷 Translation Request
2+
description: Request a translation
3+
title: "[🇧🇷 Translation]: "
4+
labels: [translate-ja, translate-pt-br, translate-zh-cn]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for taking the time to request content to be translated. We are currently providing
10+
translations in our documentation for Japanese, Chinese, and Brazilian Portuguese.
11+
- type: textarea
12+
id: translation-description
13+
attributes:
14+
label: What needs to be translated
15+
description: |
16+
Link to the content or Pull Request that needs an updated translation.
17+
validations:
18+
required: true

‎website_and_docs/content/documentation/ie_driver_server.en.md

+183
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: "IE Driver Server"
3+
linkTitle: "IE Driver Server"
4+
weight: 8
5+
description: >
6+
The Internet Explorer Driver is a standalone server that implements the WebDriver specification.
7+
---
8+
9+
The `InternetExplorerDriver` is a standalone server which implements WebDriver's wire protocol.
10+
This driver has been tested with IE 11, and on Windows 10. It might work with older versions
11+
of IE and Windows, but this is not supported.
12+
13+
The driver supports running 32-bit and 64-bit versions of the browser. The choice of how to
14+
determine which "bit-ness" to use in launching the browser depends on which version of the
15+
IEDriverServer.exe is launched. If the 32-bit version of `IEDriverServer.exe` is launched,
16+
the 32-bit version of IE will be launched. Similarly, if the 64-bit version of
17+
IEDriverServer.exe is launched, the 64-bit version of IE will be launched.
18+
19+
## Installing
20+
21+
You do not need to run an installer before using the `InternetExplorerDriver`, though some
22+
configuration is required. The standalone server executable must be downloaded from
23+
the [Downloads](https://www.selenium.dev/downloads/) page and placed in your
24+
[PATH](http://en.wikipedia.org/wiki/PATH_(variable)).
25+
26+
## Pros
27+
28+
* Runs in a real browser and supports JavaScript
29+
30+
## Cons
31+
32+
* Obviously the InternetExplorerDriver will only work on Windows!
33+
* Comparatively slow (though still pretty snappy :)
34+
35+
## Command-Line Switches
36+
37+
As a standalone executable, the behavior of the IE driver can be modified through various
38+
command-line arguments. To set the value of these command-line arguments, you should
39+
consult the documentation for the language binding you are using. The command line
40+
switches supported are described in the table below. All -`<switch>`, --`<switch>`
41+
and /`<switch>` are supported.
42+
43+
| Switch | Meaning |
44+
|:-------|:--------|
45+
| --port=`<portNumber>` | Specifies the port on which the HTTP server of the IE driver will listen for commands from language bindings. Defaults to 5555. |
46+
| --host=`<hostAdapterIPAddress>` | Specifies the IP address of the host adapter on which the HTTP server of the IE driver will listen for commands from language bindings. Defaults to 127.0.0.1. |
47+
| --log-level=`<logLevel>` | Specifies the level at which logging messages are output. Valid values are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. Defaults to FATAL. |
48+
| --log-file=`<logFile>` | Specifies the full path and file name of the log file. Defaults to stdout. |
49+
| --extract-path=`<path>` | Specifies the full path to the directory used to extract supporting files used by the server. Defaults to the TEMP directory if not specified. |
50+
| --silent | Suppresses diagnostic output when the server is started. |
51+
52+
## Important System Properties
53+
54+
The following system properties (read using `System.getProperty()` and set using
55+
`System.setProperty()` in Java code or the "`-DpropertyName=value`" command line flag)
56+
are used by the `InternetExplorerDriver`:
57+
58+
| **Property** | **What it means** |
59+
|:-------------|:------------------|
60+
| `webdriver.ie.driver` | The location of the IE driver binary. |
61+
| `webdriver.ie.driver.host` | Specifies the IP address of the host adapter on which the IE driver will listen. |
62+
| `webdriver.ie.driver.loglevel` | Specifies the level at which logging messages are output. Valid values are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. Defaults to FATAL. |
63+
| `webdriver.ie.driver.logfile` | Specifies the full path and file name of the log file. |
64+
| `webdriver.ie.driver.silent` | Suppresses diagnostic output when the IE driver is started. |
65+
| `webdriver.ie.driver.extractpath` | Specifies the full path to the directory used to extract supporting files used by the server. Defaults to the TEMP directory if not specified. |
66+
67+
## Required Configuration
68+
69+
* The `IEDriverServer` executable must be [downloaded](https://www.selenium.dev/downloads/) and placed in your [PATH](http://en.wikipedia.org/wiki/PATH_(variable)).
70+
* On IE 7 or higher on Windows Vista, Windows 7, or Windows 10, you must set the Protected Mode settings for each zone to be the same value. The value can be on or off, as long as it is the same for every zone. To set the Protected Mode settings, choose "Internet Options..." from the Tools menu, and click on the Security tab. For each zone, there will be a check box at the bottom of the tab labeled "Enable Protected Mode".
71+
* Additionally, "Enhanced Protected Mode" must be disabled for IE 10 and higher. This option is found in the Advanced tab of the Internet Options dialog.
72+
* The browser zoom level must be set to 100% so that the native mouse events can be set to the correct coordinates.
73+
* For Windows 10, you also need to set "Change the size of text, apps, and other items" to 100% in display settings.
74+
* For IE 11 _only_, you will need to set a registry entry on the target computer so that the driver can maintain a connection to the instance of Internet Explorer it creates. For 32-bit Windows installations, the key you must examine in the registry editor is `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_BFCACHE`. For 64-bit Windows installations, the key is `HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_BFCACHE`. Please note that the `FEATURE_BFCACHE` subkey may or may not be present, and should be created if it is not present. **Important:** Inside this key, create a DWORD value named `iexplore.exe` with the value of 0.
75+
76+
## Native Events and Internet Explorer
77+
78+
As the `InternetExplorerDriver` is Windows-only, it attempts to use so-called "native", or OS-level
79+
events to perform mouse and keyboard operations in the browser. This is in contrast to using
80+
simulated JavaScript events for the same operations. The advantage of using native events is that
81+
it does not rely on the JavaScript sandbox, and it ensures proper JavaScript event propagation
82+
within the browser. However, there are currently some issues with mouse events when the IE
83+
browser window does not have focus, and when attempting to hover over elements.
84+
85+
### Browser Focus
86+
87+
The challenge is that IE itself appears to not fully respect the Windows messages we send the
88+
IE browser window (`WM\_MOUSEDOWN` and `WM\_MOUSEUP`) if the window doesn't have the focus.
89+
Specifically, the element being clicked on will receive a focus window around it, but the click
90+
will not be processed by the element. Arguably, we shouldn't be sending messages at all; rather,
91+
we should be using the `SendInput()` API, but that API explicitly requires the window to have the
92+
focus. We have two conflicting goals with the WebDriver project.
93+
94+
First, we strive to emulate the user as closely as possible. This means using native events
95+
rather than simulating the events using JavaScript.
96+
97+
Second, we want to not require focus of the browser window being automated. This means that
98+
just forcing the browser window to the foreground is suboptimal.
99+
100+
An additional consideration is the possibility of multiple IE instances running under multiple
101+
WebDriver instances, which means any such "bring the window to the foreground" solution will
102+
have to be wrapped in some sort of synchronizing construct (mutex?) within the IE driver's
103+
C++ code. Even so, this code will still be subject to race conditions, if, for example, the
104+
user brings another window to the foreground between the driver bringing IE to the foreground
105+
and executing the native event.
106+
107+
The discussion around the requirements of the driver and how to prioritize these two
108+
conflicting goals is ongoing. The current prevailing wisdom is to prioritize the former over
109+
the latter, and document that your machine will be unavailable for other tasks when using
110+
the IE driver. However, that decision is far from finalized, and the code to implement it is
111+
likely to be rather complicated.
112+
113+
### Hovering Over Elements
114+
115+
When you attempt to hover over elements, and your physical mouse cursor is within the boundaries
116+
of the IE browser window, the hover will not work. More specifically, the hover will appear
117+
to work for a fraction of a second, and then the element will revert back to its previous
118+
state. The prevailing theory why this occurs is that IE is doing hit-testing of some sort
119+
during its event loop, which causes it to respond to the physical mouse position when the
120+
physical cursor is within the window bounds. The WebDriver development team has been unable
121+
to discover a workaround for this behavior of IE.
122+
123+
### Clicking `<option>` Elements or Submitting Forms and `alert()`
124+
125+
There are two places where the IE driver does not interact with elements using native events.
126+
This is in clicking `<option>` elements within a `<select>` element. Under normal circumstances,
127+
the IE driver calculates where to click based on the position and size of the element, typically
128+
as returned by the JavaScript `getBoundingClientRect()` method. However, for `<option>` elements,
129+
`getBoundingClientRect()` returns a rectangle with zero position and zero size. The IE driver
130+
handles this one scenario by using the `click()` Automation Atom, which essentially sets
131+
the `.selected` property of the element and simulates the `onChange` event in JavaScript.
132+
However, this means that if the `onChange` event of the `<select>` element contains JavaScript
133+
code that calls `alert()`, `confirm()` or `prompt()`, calling WebElement's `click()` method will
134+
hang until the modal dialog is manually dismissed. There is no known workaround for this behavior
135+
using only WebDriver code.
136+
137+
Similarly, there are some scenarios when submitting an HTML form via WebElement's `submit()`
138+
method may have the same effect. This can happen if the driver calls the JavaScript `submit()`
139+
function on the form, and there is an onSubmit event handler that calls the JavaScript `alert()`,
140+
`confirm()`, or `prompt()` functions.
141+
142+
This restriction is filed as issue 3508 (on Google Code).
143+
144+
## Multiple instances of `InternetExplorerDriver`
145+
146+
With the creation of the `IEDriverServer.exe`, it should be possible to create and use multiple
147+
simultaneous instances of the `InternetExplorerDriver`. However, this functionality is largely
148+
untested, and there may be issues with cookies, window focus, and the like. If you attempt to
149+
use multiple instances of the IE driver, and run into such issues, consider using the
150+
`RemoteWebDriver` and virtual machines.
151+
152+
There are 2 solutions for problem with cookies (and another session items) shared between
153+
multiple instances of InternetExplorer.
154+
155+
The first is to start your InternetExplorer in private mode. After that InternetExplorer will be
156+
started with clean session data and will not save changed session data at quiting. To do so you
157+
need to pass 2 specific capabilities to driver: `ie.forceCreateProcessApi` with `true` value
158+
and `ie.browserCommandLineSwitches` with `-private` value. Be note that it will work only
159+
for InternetExplorer 8 and newer, and Windows Registry
160+
`HKLM_CURRENT_USER\\Software\\Microsoft\\Internet Explorer\\Main` path should contain key
161+
`TabProcGrowth` with `0` value.
162+
163+
The second is to clean session during InternetExplorer starting. For this you need to pass
164+
specific `ie.ensureCleanSession` capability with `true` value to driver. This clears the cache
165+
for all running instances of InternetExplorer, including those started manually.
166+
167+
## Running `IEDriverServer.exe` Remotely
168+
169+
The HTTP server started by the `IEDriverServer.exe` sets an access control list to only accept
170+
connections from the local machine, and disallows incoming connections from remote machines.
171+
At present, this cannot be changed without modifying the source code to the `IEDriverServer.exe`.
172+
To run the Internet Explorer driver on a remote machine, use the Java standalone remote server
173+
in connection with your language binding's equivalent of `RemoteWebDriver`.
174+
175+
## Running `IEDriverServer.exe` Under a Windows Service
176+
177+
Attempting to use IEDriverServer.exe as part of a Windows Service application is expressly
178+
unsupported. Service processes, and processes spawned by them, have much different requirements
179+
than those executing in a regular user context. `IEDriverServer.exe` is explicitly untested in
180+
that environment, and includes Windows API calls that are documented to be prohibited to be used
181+
in service processes. While it may be possible to get the IE driver to work while running under
182+
a service process, users encountering problems in that environment will need to seek out their
183+
own solutions.

0 commit comments

Comments
 (0)