Skip to content

Commit fd8a67f

Browse files
krmahadevankrmahadevan
authored
Add docs for download-paths (#1262)
Adding documentation that explains how to specify a directory from which tests can now download files that were downloaded by them on the node.
1 parent 3dc0bc7 commit fd8a67f

File tree

8 files changed

+402
-0
lines changed

8 files changed

+402
-0
lines changed

‎website_and_docs/content/documentation/grid/configuration/cli_options.en.md

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,7 @@ pull request updating this page.
224224
| `--drain-after-session-count`| int | `1` | Drain and shutdown the Node after X sessions have been executed. Useful for environments like Kubernetes. A value higher than zero enables this feature. |
225225
| `--hub`| string | `http://localhost:4444` | The address of the Hub in a Hub-and-Node configuration. Can be a hostname or IP address (`hostname`), in which case the Hub will be assumed to be `http://hostname:4444`, the `--grid-url` will be the same `--publish-events` will be `tcp://hostname:4442` and `--subscribe-events` will be `tcp://hostname:4443`. If `hostname` contains a port number, that will be used for `--grid-url` but the URIs for the event bus will remain the same. Any of these default values may be overridden but setting the correct flags. If the hostname has a protocol (such as `https`) that will be used too. |
226226
| `--enable-cdp`| boolean | `true` | Enable CDP proxying in Grid. A Grid admin can disable CDP if the network doesnot allow websockets. True by default. |
227+
| `--downloads-path`| string | `/usr/downloads` | The default location wherein all browser triggered file downloads would be available to be retrieved from. This is usually the directory that you configure in your browser as the default location for storing downloaded files. |
227228

228229
### Relay
229230

@@ -349,3 +350,92 @@ driver.quit();
349350
```
350351

351352
Set the custom capability to `false` in order to match the Node B.
353+
354+
#### Specifying path from where downloaded files can be retrieved
355+
356+
At times a test may need to access files that were downloaded by it on the Node. To retrieve such files, following can be done.
357+
358+
##### Start the Hub
359+
```
360+
java -jar selenium-server-<version>.jar hub
361+
```
362+
363+
##### Start the Node with downloads path specified
364+
```
365+
java -jar selenium-server-<version>.jar node --downloads-path /usr/downloads
366+
```
367+
368+
##### Sample that retrieves the downloaded file
369+
370+
```java
371+
import static org.openqa.selenium.remote.http.Contents.string;
372+
373+
import java.io.File;
374+
import java.io.IOException;
375+
import java.net.URL;
376+
import java.util.Map;
377+
import java.util.concurrent.TimeUnit;
378+
import org.openqa.selenium.By;
379+
import org.openqa.selenium.WebElement;
380+
import org.openqa.selenium.firefox.FirefoxOptions;
381+
import org.openqa.selenium.io.Zip;
382+
import org.openqa.selenium.json.Json;
383+
import org.openqa.selenium.remote.RemoteWebDriver;
384+
import org.openqa.selenium.remote.http.HttpClient;
385+
import org.openqa.selenium.remote.http.HttpMethod;
386+
import org.openqa.selenium.remote.http.HttpRequest;
387+
import org.openqa.selenium.remote.http.HttpResponse;
388+
389+
public class DownloadsSample {
390+
391+
public static void main(String[] args) throws InterruptedException, IOException {
392+
File dirToCopyTo = new File("/usr/downloads");
393+
URL gridUrl = new URL("http://localhost:4444");
394+
RemoteWebDriver driver = new RemoteWebDriver(gridUrl, firefoxOptions());
395+
driver.get("http://the-internet.herokuapp.com/download");
396+
WebElement element = driver.findElement(By.cssSelector(".example a"));
397+
element.click();
398+
399+
TimeUnit.SECONDS.sleep(10);
400+
401+
// The file can be downloaded by accessing
402+
// curl -X GET "http://localhost:4444/session/<sessionId>/se/file?filename=my_file.pdf"
403+
404+
HttpRequest request = new HttpRequest(
405+
HttpMethod.GET,
406+
String.format("/session/%s/se/file", driver.getSessionId()));
407+
request.addQueryParameter("filename", "my_appointments-1.pdf");
408+
try (HttpClient client = HttpClient.Factory.createDefault().createClient(gridUrl)) {
409+
HttpResponse response = client.execute(request);
410+
Map<String, Object> map = new Json().toType(string(response), Json.MAP_TYPE);
411+
// The returned map would contain 2 keys viz.,
412+
// filename - This represents the name of the file (same as what was provided by the test)
413+
// contents - Base64 encoded String which contains the zipped file.
414+
String encodedContents = map.get("contents").toString();
415+
416+
//The file contents would always be a zip file and has to be unzipped.
417+
Zip.unzip(encodedContents, dirToCopyTo);
418+
} finally {
419+
driver.quit();
420+
}
421+
}
422+
423+
private static FirefoxOptions firefoxOptions() {
424+
FirefoxOptions options = new FirefoxOptions();
425+
options.addPreference("browser.download.manager.showWhenStarting", false);
426+
options.addPreference("browser.helperApps.neverAsk.saveToDisk",
427+
"images/jpeg, application/pdf, application/octet-stream");
428+
options.addPreference("pdfjs.disabled", true);
429+
return options;
430+
}
431+
}
432+
```
433+
434+
##### Points to remember:
435+
436+
* The endpoint to `GET` from is `/session/<sessionId>/se/file?filename=`
437+
* The response contains two keys viz.,
438+
* `filename` - Same as what was specified in the request.
439+
* `contents` - Base64 encoded zipped contents of the file.
440+
* The file contents are Base64 encoded.
441+
* The contents need to be unzipped.

‎website_and_docs/content/documentation/grid/configuration/cli_options.ja.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,7 @@ Grid の設定には、さまざまなセクションが用意されています
223223
| `--drain-after-session-count` | int | `1` | X 個のセッションが実行された後に、ノードをドレインしてシャットダウンします。 Kubernetes のような環境で有用です。 0 より大きい値を指定すると、この機能が有効になります。 |
224224
| `--hub` | string | `http://localhost:4444` | ハブ・ノード構成におけるハブのアドレスを指定します。ホスト名か IP アドレスが指定できます。この場合、ハブは `http://hostname:4444` とみなされ、 `--grid-url` は同じものになります。 `--publish-events` は `tcp://hostname:4442` 、`--subscribe-events` は `tcp://hostname:4443` となります。 `hostname` にポート番号が含まれている場合は、それが `--grid-url` に使用されますが、イベントバスの URI は変更されません。これらのデフォルト値は、適切なフラグを設定することでオーバーライドすることができます。ホスト名にプロトコル(`https`のような)が含まれる場合もそれが利用されます。 |
225225
| `--enable-cdp` | boolean | `true` | Grid 内で CDP プロキシーを有効にします。もしネットワークが web socket を許可していない場合、Grid 管理者は CDP を無効にできます。デフォルトは true です。 |
226+
| `--downloads-path`| string | `/usr/downloads` | The default location wherein all browser triggered file downloads would be available to be retrieved from. This is usually the directory that you configure in your browser as the default location for storing downloaded files. |
226227

227228
### Relay
228229

@@ -349,3 +350,93 @@ driver.quit();
349350
```
350351

351352
ノード B とマッチさせるにはカスタム capability を `false` に設定します。
353+
354+
355+
#### Specifying path from where downloaded files can be retrieved
356+
357+
At times a test may need to access files that were downloaded by it on the Node. To retrieve such files, following can be done.
358+
359+
##### Start the Hub
360+
```
361+
java -jar selenium-server-<version>.jar hub
362+
```
363+
364+
##### Start the Node with downloads path specified
365+
```
366+
java -jar selenium-server-<version>.jar node --downloads-path /usr/downloads
367+
```
368+
369+
##### Sample that retrieves the downloaded file
370+
371+
```java
372+
import static org.openqa.selenium.remote.http.Contents.string;
373+
374+
import java.io.File;
375+
import java.io.IOException;
376+
import java.net.URL;
377+
import java.util.Map;
378+
import java.util.concurrent.TimeUnit;
379+
import org.openqa.selenium.By;
380+
import org.openqa.selenium.WebElement;
381+
import org.openqa.selenium.firefox.FirefoxOptions;
382+
import org.openqa.selenium.io.Zip;
383+
import org.openqa.selenium.json.Json;
384+
import org.openqa.selenium.remote.RemoteWebDriver;
385+
import org.openqa.selenium.remote.http.HttpClient;
386+
import org.openqa.selenium.remote.http.HttpMethod;
387+
import org.openqa.selenium.remote.http.HttpRequest;
388+
import org.openqa.selenium.remote.http.HttpResponse;
389+
390+
public class DownloadsSample {
391+
392+
public static void main(String[] args) throws InterruptedException, IOException {
393+
File dirToCopyTo = new File("/usr/downloads");
394+
URL gridUrl = new URL("http://localhost:4444");
395+
RemoteWebDriver driver = new RemoteWebDriver(gridUrl, firefoxOptions());
396+
driver.get("http://the-internet.herokuapp.com/download");
397+
WebElement element = driver.findElement(By.cssSelector(".example a"));
398+
element.click();
399+
400+
TimeUnit.SECONDS.sleep(10);
401+
402+
// The file can be downloaded by accessing
403+
// curl -X GET "http://localhost:4444/session/<sessionId>/se/file?filename=my_file.pdf"
404+
405+
HttpRequest request = new HttpRequest(
406+
HttpMethod.GET,
407+
String.format("/session/%s/se/file", driver.getSessionId()));
408+
request.addQueryParameter("filename", "my_appointments-1.pdf");
409+
try (HttpClient client = HttpClient.Factory.createDefault().createClient(gridUrl)) {
410+
HttpResponse response = client.execute(request);
411+
Map<String, Object> map = new Json().toType(string(response), Json.MAP_TYPE);
412+
// The returned map would contain 2 keys viz.,
413+
// filename - This represents the name of the file (same as what was provided by the test)
414+
// contents - Base64 encoded String which contains the zipped file.
415+
String encodedContents = map.get("contents").toString();
416+
417+
//The file contents would always be a zip file and has to be unzipped.
418+
Zip.unzip(encodedContents, dirToCopyTo);
419+
} finally {
420+
driver.quit();
421+
}
422+
}
423+
424+
private static FirefoxOptions firefoxOptions() {
425+
FirefoxOptions options = new FirefoxOptions();
426+
options.addPreference("browser.download.manager.showWhenStarting", false);
427+
options.addPreference("browser.helperApps.neverAsk.saveToDisk",
428+
"images/jpeg, application/pdf, application/octet-stream");
429+
options.addPreference("pdfjs.disabled", true);
430+
return options;
431+
}
432+
}
433+
```
434+
435+
##### Points to remember:
436+
437+
* The endpoint to `GET` from is `/session/<sessionId>/se/file?filename=`
438+
* The response contains two keys viz.,
439+
* `filename` - Same as what was specified in the request.
440+
* `contents` - Base64 encoded zipped contents of the file.
441+
* The file contents are Base64 encoded.
442+
* The contents need to be unzipped.

‎website_and_docs/content/documentation/grid/configuration/cli_options.pt-br.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,8 @@ e esteja à vontade para nos enviar um pull request com alterações a esta pág
226226
| `--drain-after-session-count`| int | `1` | Drain and shutdown the Node after X sessions have been executed. Useful for environments like Kubernetes. A value higher than zero enables this feature. |
227227
| `--hub`| string | `http://localhost:4444` | The address of the Hub in a Hub-and-Node configuration. Can be a hostname or IP address (`hostname`), in which case the Hub will be assumed to be `http://hostname:4444`, the `--grid-url` will be the same `--publish-events` will be `tcp://hostname:4442` and `--subscribe-events` will be `tcp://hostname:4443`. If `hostname` contains a port number, that will be used for `--grid-url` but the URIs for the event bus will remain the same. Any of these default values may be overridden but setting the correct flags. If the hostname has a protocol (such as `https`) that will be used too. |
228228
| `--enable-cdp`| boolean | `true` | Enable CDP proxying in Grid. A Grid admin can disable CDP if the network doesnot allow websockets. True by default. |
229+
| `--downloads-path`| string | `/usr/downloads` | The default location wherein all browser triggered file downloads would be available to be retrieved from. This is usually the directory that you configure in your browser as the default location for storing downloaded files. |
230+
229231

230232
### Relay
231233

@@ -351,3 +353,93 @@ driver.quit();
351353
```
352354

353355
Set the custom capability to `false` in order to match the Node B.
356+
357+
358+
#### Specifying path from where downloaded files can be retrieved
359+
360+
At times a test may need to access files that were downloaded by it on the Node. To retrieve such files, following can be done.
361+
362+
##### Start the Hub
363+
```
364+
java -jar selenium-server-<version>.jar hub
365+
```
366+
367+
##### Start the Node with downloads path specified
368+
```
369+
java -jar selenium-server-<version>.jar node --downloads-path /usr/downloads
370+
```
371+
372+
##### Sample that retrieves the downloaded file
373+
374+
```java
375+
import static org.openqa.selenium.remote.http.Contents.string;
376+
377+
import java.io.File;
378+
import java.io.IOException;
379+
import java.net.URL;
380+
import java.util.Map;
381+
import java.util.concurrent.TimeUnit;
382+
import org.openqa.selenium.By;
383+
import org.openqa.selenium.WebElement;
384+
import org.openqa.selenium.firefox.FirefoxOptions;
385+
import org.openqa.selenium.io.Zip;
386+
import org.openqa.selenium.json.Json;
387+
import org.openqa.selenium.remote.RemoteWebDriver;
388+
import org.openqa.selenium.remote.http.HttpClient;
389+
import org.openqa.selenium.remote.http.HttpMethod;
390+
import org.openqa.selenium.remote.http.HttpRequest;
391+
import org.openqa.selenium.remote.http.HttpResponse;
392+
393+
public class DownloadsSample {
394+
395+
public static void main(String[] args) throws InterruptedException, IOException {
396+
File dirToCopyTo = new File("/usr/downloads");
397+
URL gridUrl = new URL("http://localhost:4444");
398+
RemoteWebDriver driver = new RemoteWebDriver(gridUrl, firefoxOptions());
399+
driver.get("http://the-internet.herokuapp.com/download");
400+
WebElement element = driver.findElement(By.cssSelector(".example a"));
401+
element.click();
402+
403+
TimeUnit.SECONDS.sleep(10);
404+
405+
// The file can be downloaded by accessing
406+
// curl -X GET "http://localhost:4444/session/<sessionId>/se/file?filename=my_file.pdf"
407+
408+
HttpRequest request = new HttpRequest(
409+
HttpMethod.GET,
410+
String.format("/session/%s/se/file", driver.getSessionId()));
411+
request.addQueryParameter("filename", "my_appointments-1.pdf");
412+
try (HttpClient client = HttpClient.Factory.createDefault().createClient(gridUrl)) {
413+
HttpResponse response = client.execute(request);
414+
Map<String, Object> map = new Json().toType(string(response), Json.MAP_TYPE);
415+
// The returned map would contain 2 keys viz.,
416+
// filename - This represents the name of the file (same as what was provided by the test)
417+
// contents - Base64 encoded String which contains the zipped file.
418+
String encodedContents = map.get("contents").toString();
419+
420+
//The file contents would always be a zip file and has to be unzipped.
421+
Zip.unzip(encodedContents, dirToCopyTo);
422+
} finally {
423+
driver.quit();
424+
}
425+
}
426+
427+
private static FirefoxOptions firefoxOptions() {
428+
FirefoxOptions options = new FirefoxOptions();
429+
options.addPreference("browser.download.manager.showWhenStarting", false);
430+
options.addPreference("browser.helperApps.neverAsk.saveToDisk",
431+
"images/jpeg, application/pdf, application/octet-stream");
432+
options.addPreference("pdfjs.disabled", true);
433+
return options;
434+
}
435+
}
436+
```
437+
438+
##### Points to remember:
439+
440+
* The endpoint to `GET` from is `/session/<sessionId>/se/file?filename=`
441+
* The response contains two keys viz.,
442+
* `filename` - Same as what was specified in the request.
443+
* `contents` - Base64 encoded zipped contents of the file.
444+
* The file contents are Base64 encoded.
445+
* The contents need to be unzipped.

0 commit comments

Comments
 (0)