-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
129 lines (102 loc) · 5.11 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
available <- selenider::selenider_available()
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%",
eval = available
)
```
```{r, eval = !available, include = FALSE}
message("Selenider is not available")
```
# selenider
<!-- badges: start -->
[](https://github.com/ashbythorpe/selenider/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/ashbythorpe/selenider?branch=main)
[](https://CRAN.R-project.org/package=selenider)
<!-- badges: end -->
Traditionally, automating a web browser is often unreliable, especially when using R.
Programmers are forced to write verbose code, utilising inconsistent workarounds (such as using
`Sys.sleep()` to wait for something to happen).
selenider aims to make web testing and scraping in R much simpler, providing a wrapper for either [chromote](https://rstudio.github.io/chromote/)
or [selenium](https://ashbythorpe.github.io/selenium-r/). It is inspired by Java's [Selenide](https://selenide.org/) and Python's [Selene](https://yashaka.github.io/selene/).
Code reliability and reproducibility are essential when writing R code. selenider provides features to
make your scripts work every time they are run, without any extra code:
* Lazy elements: selenider will only try to find an element on the page when it is absolutely necessary.
Your definitions of HTML elements are separated from their existence on the page, only allowing
the two to converge when absolutely necessary. In selenider, HTML elements are stored as the directions
to the element on the page, rather than the element itself. This is much more reliable than the
alternative since the webpage can constantly change, resulting in elements becoming invalid between their
creation and use (e.g. the dreaded `StaleElementReferenceException` in Selenium).
* Automatic waiting: selenider will automatically wait for your code to work (e.g. waiting for an input to
exist and be clickable before actually clicking it), allowing you to write scripts as if your website
always responds instantly to your interactions.
selenider's other main focus is its API. Its design choices result in concise yet expressive
code that is easy to read and easy to write:
* A global session object results in shorter, more declarative code. It also allows the session to be
created at the beginning of your script or test, and closed at the end.
* All functions are designed for use with the pipe operator (`|>` or `%>%`); elements can be selected,
tested and operated on in a single pipeline.
* `elem_expect()` is a powerful way to specify test expectations, with a simple but extensible syntax
and informative error messages.
* selenider is compatible with automated testing frameworks like [testthat](https://testthat.r-lib.org) and [shinytest2](https://rstudio.github.io/shinytest2/).
## Installation
``` r
# Install selenider from CRAN
install.packages("selenider")
# Or the development version from Github
# install.packages("remotes")
remotes::install_github("ashbythorpe/selenider")
```
Additionally, you must install [chromote](https://rstudio.github.io/chromote/)
or [selenium](https://ashbythorpe.github.io/selenium-r/).
We recommend chromote, as it is quicker and easier to get up and running.
``` r
# Either:
install.packages("chromote")
# Or:
install.packages("selenium")
```
If you are using selenium, you must also have [Java](https://www.oracle.com/java/technologies/downloads/) installed.
Finally, you must have a web browser installed. For chromote, [Google Chrome](https://www.google.com/chrome/) is
required. For selenium, any browser can be used, but [Firefox](https://www.mozilla.org/firefox/new/) is recommended.
## Usage
```{r}
library(selenider)
```
The following code navigates to the [R project website](https://www.r-project.org/), finds the link to
the CRAN mirror list, checks that the link is correct, and clicks the link element.
```{r}
open_url("https://www.r-project.org/")
s(".row") |>
find_element("div") |>
find_elements("a") |>
elem_find(has_text("CRAN")) |>
elem_expect(attr_contains("href", "cran.r-project.org")) |>
elem_click()
```
Now that we're in the mirror list page, let's find the link to every CRAN mirror in the UK.
```{r}
s("dl") |>
find_elements("dt") |>
elem_find(has_text("UK")) |>
find_element(xpath = "./following-sibling::dd") |>
find_elements("tr") |>
elem_expect(has_at_least(1)) |>
as.list() |>
lapply(
\(x) x |>
find_element("a") |>
elem_attr("href")
)
```
## Vignettes
* Get started with selenider, and learn the basics: `vignette("selenider")`.
* Use selenider with testthat, shinytest2 and Github Actions: `vignette("unit-testing", package = "selenider")`.
* Use selenider with rvest: `vignette("with-rvest", package = "selenider")`