Skip to content

Commit fa2bcea

Browse files
gaborcsardigaborcsardi
committed
Add README
1 parent 4e4d9d9 commit fa2bcea

File tree

8 files changed

+336
-33
lines changed

8 files changed

+336
-33
lines changed

‎.Rbuildignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
^.*\.Rproj$
22
^\.Rproj\.user$
33
^Makefile$
4-
^README.Rmd$
4+
^README.markdown$
55
^.travis.yml$
66
^appveyor.yml$

‎Makefile

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
2+
inst/README.markdown: inst/README.Rmd
3+
Rscript -e "library(knitr); knit('$<', output = '$@', quiet = TRUE)"

‎README.markdown

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
inst/README.markdown

‎README.md

Lines changed: 0 additions & 32 deletions
This file was deleted.

‎inst/README.Rmd

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
2+
```{r, setup, echo = FALSE, message = FALSE}
3+
knitr::opts_chunk$set(
4+
tidy = FALSE,
5+
fig.width = 4,
6+
fig.height = 12,
7+
fig.path = "inst/")
8+
```
9+
10+
# webdriver
11+
12+
> 'WebDriver' Client for 'PhantomJS'
13+
14+
[![Linux Build Status](https://travis-ci.org/rstudio/webdriver.svg?branch=master)](https://travis-ci.org/rstudio/webdriver)
15+
[![Windows Build status](https://ci.appveyor.com/api/projects/status/github/rstudio/webdriver?svg=true)](https://ci.appveyor.com/project/rstudio/webdriver)
16+
[![](http://www.r-pkg.org/badges/version/webdriver)](http://www.r-pkg.org/pkg/webdriver)
17+
[![CRAN RStudio mirror downloads](http://cranlogs.r-pkg.org/badges/webdriver)](http://www.r-pkg.org/pkg/webdriver)
18+
[![Coverage Status](https://img.shields.io/codecov/c/github/rstudio/webdriver/master.svg)](https://codecov.io/github/rstudio/webdriver?branch=master)
19+
20+
21+
A client for the 'WebDriver' 'API'. It allows driving a (probably headless)
22+
web browser, and can be used to test web applications, including 'Shiny'
23+
apps. In theory it works with any 'WebDriver' implementation, but it was only
24+
tested with 'PhantomJS'.
25+
26+
## Installation
27+
28+
```r
29+
source("https://install-github.me/rstudio/webdriver")
30+
```
31+
32+
## Usage
33+
34+
```{r}
35+
library(webdriver)
36+
```
37+
38+
### PhantomJS
39+
40+
webdriver uses PhantomJS as a headless web browser. (In theory in works
41+
with other WebDriver clients as well.) You can use the `install_phantomjs()`
42+
function to download and install PhantomJS on your system. Alternatively
43+
an installation that is in the PATH is sufficient.
44+
45+
The `run_phantomjs()` function starts PhantomJS, and waits until it is ready
46+
to serve queries. It returns a process object that you can terminate
47+
manually, and the port on which PhantomJS is listening.
48+
49+
```{r}
50+
pjs <- run_phantomjs()
51+
pjs
52+
```
53+
54+
### Sessions
55+
56+
Use the `Session` class to connection to a running PhantomJS process.
57+
One process can save multiple sessions, and the sessions are independent
58+
of each other.
59+
60+
```{r}
61+
ses <- Session$new(port = pjs$port)
62+
```
63+
64+
Once a session is established, you can manipulate the headless web browser
65+
through it:
66+
67+
```{r}
68+
ses$go("https://r-pkg.org/pkg/callr")
69+
ses$getUrl()
70+
ses$getTitle()
71+
```
72+
73+
You can also take a screenshot of the whole web page, and show it on R's
74+
graphics device, or save it to a PNG file:
75+
76+
77+
```{r screenshot-1}
78+
ses$takeScreenshot()
79+
```
80+
81+
### HTML elements
82+
83+
The `Session` object has two methods to find HTML elements on the current
84+
web page, which can then be further manipulated: `findElement()` and
85+
`findElements()`. They work with CSS or XPATH selectors, and also with
86+
(possibly partial) HTML text.
87+
88+
```{r}
89+
install <- ses$findElement(".install-package")
90+
install$getName()
91+
install$getText()
92+
```
93+
94+
If you have an HTML element that can receive keyboard keys, you can use
95+
the `sendKeys()` method to send them. The `key` list helps with sending
96+
special, characters, e.g. `key$enter` corresponds to pressing ENTER. For
97+
example we can type into a search box:
98+
99+
```{r screenshot-2}
100+
search <- ses$findElement("#cran-input")
101+
search$sendKeys("html", key$enter)
102+
ses$getUrl()
103+
ses$getTitle()
104+
ses$takeScreenshot()
105+
```
106+
107+
### JavaScript
108+
109+
The `executeScript()` method of a `Session` object runs arbitrary JavaScript
110+
in the headless browser. It puts the supplied code into the body of a
111+
JavaScript function, and the function will receive the additional arguments,
112+
in its `arguments` array. `Element` objects as arguments are automatically
113+
converted to the corresponding DOM elements in the browser.
114+
115+
The JavaScript function can return values to R. Returned HTML elements are
116+
automatically converted to `Element` objects.
117+
118+
```{r}
119+
ses$executeScript("return 42 + 'foobar';")
120+
```
121+
122+
```{r}
123+
search2 <- ses$executeScript("return document.getElementById('cran-input');")
124+
search2$getName()
125+
```
126+
127+
`Element` objects also have an `executeScript()` method, which works the
128+
same way as the `Session` method, but it automatically supplies the HTML
129+
element as the first argument of the JavaScript function.
130+
131+
`executeScript()` works synchronously. If you need asynchronous execution,
132+
you can use the `executeScriptAsync()` function.
133+
134+
## License
135+
136+
MIT © Mango Solutions, RStudio

‎inst/README.markdown

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
2+
3+
4+
# webdriver
5+
6+
> 'WebDriver' Client for 'PhantomJS'
7+
8+
[![Linux Build Status](https://travis-ci.org/rstudio/webdriver.svg?branch=master)](https://travis-ci.org/rstudio/webdriver)
9+
[![Windows Build status](https://ci.appveyor.com/api/projects/status/github/rstudio/webdriver?svg=true)](https://ci.appveyor.com/project/rstudio/webdriver)
10+
[![](http://www.r-pkg.org/badges/version/webdriver)](http://www.r-pkg.org/pkg/webdriver)
11+
[![CRAN RStudio mirror downloads](http://cranlogs.r-pkg.org/badges/webdriver)](http://www.r-pkg.org/pkg/webdriver)
12+
[![Coverage Status](https://img.shields.io/codecov/c/github/rstudio/webdriver/master.svg)](https://codecov.io/github/rstudio/webdriver?branch=master)
13+
14+
15+
A client for the 'WebDriver' 'API'. It allows driving a (probably headless)
16+
web browser, and can be used to test web applications, including 'Shiny'
17+
apps. In theory it works with any 'WebDriver' implementation, but it was only
18+
tested with 'PhantomJS'.
19+
20+
## Installation
21+
22+
```r
23+
source("https://install-github.me/rstudio/webdriver")
24+
```
25+
26+
## Usage
27+
28+
29+
```r
30+
library(webdriver)
31+
```
32+
33+
### PhantomJS
34+
35+
webdriver uses PhantomJS as a headless web browser. (In theory in works
36+
with other WebDriver clients as well.) You can use the `install_phantomjs()`
37+
function to download and install PhantomJS on your system. Alternatively
38+
an installation that is in the PATH is sufficient.
39+
40+
The `run_phantomjs()` function starts PhantomJS, and waits until it is ready
41+
to serve queries. It returns a process object that you can terminate
42+
manually, and the port on which PhantomJS is listening.
43+
44+
45+
```r
46+
pjs <- run_phantomjs()
47+
pjs
48+
```
49+
50+
```
51+
## $process
52+
## PROCESS 'phantomjs', running, pid 45932.
53+
##
54+
## $port
55+
## [1] 5793
56+
```
57+
58+
### Sessions
59+
60+
Use the `Session` class to connection to a running PhantomJS process.
61+
One process can save multiple sessions, and the sessions are independent
62+
of each other.
63+
64+
65+
```r
66+
ses <- Session$new(port = pjs$port)
67+
```
68+
69+
Once a session is established, you can manipulate the headless web browser
70+
through it:
71+
72+
73+
```r
74+
ses$go("https://r-pkg.org/pkg/callr")
75+
ses$getUrl()
76+
```
77+
78+
```
79+
## [1] "https://r-pkg.org/pkg/callr"
80+
```
81+
82+
```r
83+
ses$getTitle()
84+
```
85+
86+
```
87+
## [1] "callr @ METACRAN"
88+
```
89+
90+
You can also take a screenshot of the whole web page, and show it on R's
91+
graphics device, or save it to a PNG file:
92+
93+
94+
95+
```r
96+
ses$takeScreenshot()
97+
```
98+
99+
![plot of chunk screenshot-1](inst/screenshot-1-1.png)
100+
101+
### HTML elements
102+
103+
The `Session` object has two methods to find HTML elements on the current
104+
web page, which can then be further manipulated: `findElement()` and
105+
`findElements()`. They work with CSS or XPATH selectors, and also with
106+
(possibly partial) HTML text.
107+
108+
109+
```r
110+
install <- ses$findElement(".install-package")
111+
install$getName()
112+
```
113+
114+
```
115+
## [1] "div"
116+
```
117+
118+
```r
119+
install$getText()
120+
```
121+
122+
```
123+
## [1] "install.packages(\"callr\")"
124+
```
125+
126+
If you have an HTML element that can receive keyboard keys, you can use
127+
the `sendKeys()` method to send them. The `key` list helps with sending
128+
special, characters, e.g. `key$enter` corresponds to pressing ENTER. For
129+
example we can type into a search box:
130+
131+
132+
```r
133+
search <- ses$findElement("#cran-input")
134+
search$sendKeys("html", key$enter)
135+
ses$getUrl()
136+
```
137+
138+
```
139+
## [1] "https://r-pkg.org/search.html?q=html"
140+
```
141+
142+
```r
143+
ses$getTitle()
144+
```
145+
146+
```
147+
## [1] "METACRAN search results"
148+
```
149+
150+
```r
151+
ses$takeScreenshot()
152+
```
153+
154+
![plot of chunk screenshot-2](inst/screenshot-2-1.png)
155+
156+
### JavaScript
157+
158+
The `executeScript()` method of a `Session` object runs arbitrary JavaScript
159+
in the headless browser. It puts the supplied code into the body of a
160+
JavaScript function, and the function will receive the additional arguments,
161+
in its `arguments` array. `Element` objects as arguments are automatically
162+
converted to the corresponding DOM elements in the browser.
163+
164+
The JavaScript function can return values to R. Returned HTML elements are
165+
automatically converted to `Element` objects.
166+
167+
168+
```r
169+
ses$executeScript("return 42 + 'foobar';")
170+
```
171+
172+
```
173+
## [1] "42foobar"
174+
```
175+
176+
177+
```r
178+
search2 <- ses$executeScript("return document.getElementById('cran-input');")
179+
search2$getName()
180+
```
181+
182+
```
183+
## [1] "input"
184+
```
185+
186+
`Element` objects also have an `executeScript()` method, which works the
187+
same way as the `Session` method, but it automatically supplies the HTML
188+
element as the first argument of the JavaScript function.
189+
190+
`executeScript()` works synchronously. If you need asynchronous execution,
191+
you can use the `executeScriptAsync()` function.
192+
193+
## License
194+
195+
MIT © Mango Solutions, RStudio

‎inst/screenshot-1-1.png

94.8 KB
Loading

‎inst/screenshot-2-1.png

117 KB
Loading

0 commit comments

Comments
 (0)