Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 244 lines (162 sloc) 10.107 kb
41c21fd @semperos Change README title
authored
1 # Clojure API for Selenium-WebDriver #
03ae48a @semperos Initial commit
authored
2
35fc2c4 @semperos Add OperaDriver dependencies, as well as criterium for benchmarking a…
authored
3 This is a Clojure library for driving a web browser using Selenium-WebDriver as the backend. For more comprehensive documentation on all of clj-webdriver's features, read the [Github wiki](https://github.com/semperos/clj-webdriver/wiki). You can generate documentation locally with `lein doc`.
03ae48a @semperos Initial commit
authored
4
3296292 @semperos Update README with another Selenium-WebDriver link, split up resource…
authored
5 **clj-webdriver Resources**
6
c38290a @semperos Add primary links for this project's resources to the README
authored
7 * [Project Wiki](https://github.com/semperos/clj-webdriver/wiki)
05f0d6d @semperos Add new links to API docs and Marginalia output, updated for 0.5.0-SN…
authored
8 * [API Documentation](http://techylinguist.com/static/clj-webdriver/index.html)
9 * [Marginalia Documentation (v0.5.0-SNAPSHOT)](http://techylinguist.com/static/clj-webdriver/uberdoc.html)
c38290a @semperos Add primary links for this project's resources to the README
authored
10 * [Google Group](https://groups.google.com/forum/#!forum/clj-webdriver)
11 * [Issue Queue](https://github.com/semperos/clj-webdriver/issues)
3296292 @semperos Update README with another Selenium-WebDriver link, split up resource…
authored
12
a4251c7 @semperos Add link to official CSS syntax by W3C
authored
13 **External Resources**
3296292 @semperos Update README with another Selenium-WebDriver link, split up resource…
authored
14
a4251c7 @semperos Add link to official CSS syntax by W3C
authored
15 * [Selenium-WebDriver API Javadoc](http://selenium.googlecode.com/svn/trunk/docs/api/java/index.html)
16 * [Selenium-WebDriver Changelog](http://code.google.com/p/selenium/source/browse/trunk/java/CHANGELOG)
17 * [CSS Selector Syntax](http://www.w3.org/TR/css3-selectors/#selectors)
c38290a @semperos Add primary links for this project's resources to the README
authored
18
1b5f218 @semperos Please join the Google group
authored
19 **Please join the Google group if you use this library.** I regularly post announcements about upcoming releases, and although I ensure all tests are passing and try to maintain good test coverage before releases, user testing is invaluable. Thank you!
20
4a86f36 @semperos Take out Travis status image, build breaking due to server configurat…
authored
21 ## Usage ##
03ae48a @semperos Initial commit
authored
22
0b10bda @semperos Remove notes from README about custom repository declarations
authored
23 This library is compatible with *Clojure 1.3.0*.
1507bb5 @semperos Make important points more prominent in README
authored
24
25 ### Quickstart ###
01d7b2d @semperos Fix phirsch's issue with WindowHandle not being found due to namespac…
authored
26
03ae48a @semperos Initial commit
authored
27 Use/require the library in your code:
28
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
29 ```clj
30 (use 'clj-webdriver.core)
31 ```
03ae48a @semperos Initial commit
authored
32
33 Start up a browser:
34
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
35 ```clj
f6878e0 @semperos Update README with new syntax
authored
36 (def b (start {:browser :firefox} "https://github.com"))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
37 ```
03ae48a @semperos Initial commit
authored
38
735c3cb @semperos Update README and source documentation, clean-up remnants of old READ…
authored
39 Here's an example of logging into Github:
03ae48a @semperos Initial commit
authored
40
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
41 ```clj
42 ;; Start the browser and bind it to `b`
f6878e0 @semperos Update README with new syntax
authored
43 (def b (start {:browser :firefox} "https://github.com"))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
44
45 ;; Click "Login" link
46 (-> b
47 (find-it {:text "Login"})
48 click)
49
50 ;; Input username/email into the "Login or Email" field
51 (-> b
52 (find-it {:class "text", :name "login"}) ; use multiple attributes
53 (input-text "username"))
54
55 ;; Input password into the "Password" field
56 (-> b
57 (find-it {:xpath "//input[@id='password']"}) ; :xpath and :css options
58 (input-text "password"))
59
60 ;; Click the "Log in" button"
61 (-> b
f6878e0 @semperos Update README with new syntax
authored
62 (find-it {:tag :input, :value #"(?i)log"}) ; use of regular expressions
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
63 click)
64 ```
03ae48a @semperos Initial commit
authored
65
3a69fae @semperos Add section to README for new quick-fill fn, edit other sections
authored
66 Filling out the form can been accomplished more compactly using `clj-webdriver.form-helpers/quick-fill` as follows:
67
68 ```clj
69 (require '[clj-webdriver.form-helpers :as form])
b8fea8d @semperos Update readme with more details, remove 'low level' example
authored
70
3a69fae @semperos Add section to README for new quick-fill fn, edit other sections
authored
71 (form/quick-fill b [{{:class "text", :name "login"} "username"}
72 {{:xpath "//input[@id='password']"} "password"}
73 {{:value #"(?i)log"} click}])
74 ```
75
af54249 @semperos Update README
authored
76 If you plan to submit the form, you need to pass a third parameter of `true` to prevent `quick-fill` from trying to return the elements you act upon (since the page will reload, they will be lost in the Selenium-WebDriver cache).
77
3a69fae @semperos Add section to README for new quick-fill fn, edit other sections
authored
78 ### Finding Elements ###
79
f6878e0 @semperos Update README with new syntax
authored
80 The `find-it` function provides high-level querying abilities against the DOM using HTML attribute comparisons, XPath and CSS queries, or pure-Clojure hierarchical queries. As parameters it always takes a Driver record first, followed by one of the following:
46de941 @semperos Update readme with more examples and better break-down of how to use …
authored
81
f6878e0 @semperos Update README with new syntax
authored
82 #### Attribute-Value Map ####
83
84 The attribute-value map (`attr-val`) can consist of HTML attributes, or can designate an XPath or CSS query:
85
86 ```clj
87 (find-it driver {:class "foo"})
88 (find-it driver {:tag :a, :class "bar"})
89
90 (find-it driver {:xpath "//a[@class='foo']"})
91 (find-it driver {:css "a.bar"})
92 ```
93
94 If the `:xpath` or `:css` options are used, everything else in the `attr-val` map is ignored.
95
6907a44 @semperos Add hierarhical query information back into README, reformat links
authored
96 #### Hierarchical Queries ####
97
98 If you want to build XPath or CSS-like hierarchical queries in pure Clojure, you can use the following type of forms with `find-it`:
99
100 ```clj
101 (find-it driver [{:tag :form}, {:tag :input, :type :radio, :id "foo"}])
102 ```
103
104 Note that the usual attribute-value maps are within a vector, which is what lends the ordering to the hierarchical query. On the backend, this is simply converted to XPath.
105
f6878e0 @semperos Update README with new syntax
authored
106 ##### Special Tags #####
107
6907a44 @semperos Add hierarhical query information back into README, reformat links
authored
108 By default, the `:tag` option represents a standard HTML tag like `<a>` or `<div>`. Clj-webdriver, however, supports a number of "special" tags to make using `find-it` more intuitive or concise. *(Note that these are not available inside hierarhical queries.)*
f6878e0 @semperos Update README with new syntax
authored
109
110 Here are all the special tags in action:
111
112 ```clj
113 (find-it driver {:tag :radio})
114 ;=> (find-it driver {:tag :input, :type "radio"})
115
116 (find-it driver {:tag :checkbox})
117 ;=> (find-it driver {:tag :input, :type "checkbox"})
118
119 (find-it driver {:tag :textfield})
120 ;=> (find-it driver {:tag :input, :type "text"})
121
122 (find-it driver {:tag :password})
123 ;=> (find-it driver {:tag :input, :type "password"})
124
125 (find-it driver {:tag :filefield})
126 ;=> (find-it driver {:tag :input, :type "file"})
127
128 (find-it driver {:tag :button*})
129 ```
130
131 The `:button*` option, unlike the others, conflates all button-like elements (form submit buttons, actual `<button>` tags, etc.).
46de941 @semperos Update readme with more examples and better break-down of how to use …
authored
132
6907a44 @semperos Add hierarhical query information back into README, reformat links
authored
133 #### Find-it Summary ####
134
c36bba7 @semperos Update alternative find-it functions to take a map of attr-val just l…
authored
135 To demonstrate how to use arguments in different ways, consider the following example. If I wanted to find `<a href="/contact" id="contact-link" class="menu-item" name="contact">Contact Us</a>` in a page and click on it I could perform any of the following:
136
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
137 ```clj
138 (-> b
f6878e0 @semperos Update README with new syntax
authored
139 (find-it {:tag :a}) ; assuming its the first <a> on the page
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
140 click)
141
142 (-> b
143 (find-it {:id "contact-link"}) ; :id is unique, so only one is needed
144 click)
145
146 (-> b
147 (find-it {:class "menu-item", :name "contact"}) ; use multiple attributes
148 click)
149
150 (-> b
f6878e0 @semperos Update README with new syntax
authored
151 (find-it {:tag :a, :class "menu-item", :name "contact"}) ; specify tag
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
152 click)
153
154 (-> b
f6878e0 @semperos Update README with new syntax
authored
155 (find-it {:tag :a, :text "Contact Us"}) ; special :text attribute, uses XPath's
156 click) ; text() function to find the element
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
157
158 (-> b
f6878e0 @semperos Update README with new syntax
authored
159 (find-it {:tag :a, :class #"(?i)menu-"}) ; use Java-style regular
160 click) ; expressions
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
161
162 (-> b
163 (find-it {:xpath "//a[@id='contact-link']"}) ; XPath query
164 click)
c36bba7 @semperos Update alternative find-it functions to take a map of attr-val just l…
authored
165
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
166 (-> b
167 (find-it {:css "a#contact-link"}) ; CSS selector
168 click)
169 ```
b8fea8d @semperos Update readme with more details, remove 'low level' example
authored
170
735c3cb @semperos Update README and source documentation, clean-up remnants of old READ…
authored
171 So, to describe the general pattern of interacting with the page:
172
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
173 ```clj
174 (-> browser-instance
175 (find-it options)
176 (do-something-with-the-element))
177 ```
03ae48a @semperos Initial commit
authored
178
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
179 ### Firefox Functionality
180
6907a44 @semperos Add hierarhical query information back into README, reformat links
authored
181 Support for Firefox currently exceeds that for all other browsers, most notably via support for customizable Firefox profiles. I've included support for several of these advanced featues in the `clj-webdriver.firefox` namespace. Here are a few examples (borrowed from [here](http://code.google.com/p/selenium/wiki/RubyBindings):
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
182
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
183 ```clj
184 (use 'clj-webdriver.core)
185 (require '[clj-webdriver.firefox :as ff])
186
f6878e0 @semperos Update README with new syntax
authored
187 (def b (new-driver {:browser :firefox,
188 :profile (doto (ff/new-profile)
189 ;; Enable Firebug
190 (ff/enable-extension "/path/to/extensions/firebug.xpi")))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
191
f6878e0 @semperos Update README with new syntax
authored
192 ;; Auto-download certain file types to a specific folder
193 (ff/set-preferences {:browser.download.dir "C:/Users/semperos/Desktop",
194 :browser.download.folderList 2
c33576b @semperos Correct Clojure syntax in README example for Firefox functionality
authored
195 :browser.helperApps.neverAsk.saveToDisk "application/pdf"})}))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
196 ```
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
197
aacdcb4 @semperos Add information about Grid support to the README
authored
198 ### Grid Support ###
199
6ebec51 @semperos Update README with info about Grid/RemoteWebDriver
authored
200 From a "user" perspective, working with Selenium-WebDriver's Grid 2 support behaves exactly like interacting with a locally-run RemoteWebDriver instance. See the `clj-webdriver.remote-server` and `clj-webdriver.remote-driver` namespaces for details on using this functionality.
aacdcb4 @semperos Add information about Grid support to the README
authored
201
6ebec51 @semperos Update README with info about Grid/RemoteWebDriver
authored
202 For information about configuring your Grid hub and nodes (which is handled at the command-line using the server-standalone jars), read [the Selenium-WebDriver wiki documentation on Grid 2](http://code.google.com/p/selenium/wiki/Grid2).
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
203
4b12ba5 @semperos Add instructions for contributing, branches
authored
204 ## Contributing ##
205
206 The `master` branch of clj-webdriver houses code intended for the next **minor-version release.** If you want to propose new features for the next release, you're welcome to fork, make a topic branch and issue a pull request against the `master` branch.
207
f6878e0 @semperos Update README with new syntax
authored
208 If you want to fix a bug in the **current release**, please pull against the appropriate branch for the current minor version, **0.4.x**.
4b12ba5 @semperos Add instructions for contributing, branches
authored
209
ed9aefb @semperos Update README with information about running test suite
authored
210 ## Running Tests
211
6907a44 @semperos Add hierarhical query information back into README, reformat links
authored
212 The namespace `clj-webdriver.test.example-app.core` contains a [Ring](https://github.com/mmcgrana/ring) app (routing by [Moustache](https://github.com/cgrand/moustache)) that acts as the "control application" for this project's test suite.
ed9aefb @semperos Update README with information about running test suite
authored
213
32f5593 @semperos Update docs for running tests
authored
214 Use `lein test` to run this library's test suite. Ensure port 5744 is free, or edit `test/clj_webdriver/test/core.clj` before running the tests.
ed9aefb @semperos Update README with information about running test suite
authored
215
28aa16e @semperos Update readme with how to run tests for individual browsers
authored
216 It is **highly** recommended that you run the test suite for each browser separately, as otherwise you will see strange errors. Each supported browser has its own namespace, for example:
217
218 ```
219 lein test clj-webdriver.test.firefox
220 ```
221
0b76354 @semperos Add back part of documentation that gives instructions for starting u…
authored
222 *Note:* If you just want to run the example app that clj-webdriver uses for its testing purposes, do the following:
223
224 * Open a terminal and run `lein repl` or `lein swank` at the root of this project
225 * Evaluate `(use 'clj-webdriver.test.example-app.core 'ring.adapter.jetty)`
226 * Evaluate `(defonce my-server (run-jetty #'routes {:port 5744, :join? false}))`, making sure to adjust the `test-port` in `test/clj_webdriver/test/core.clj` to whatever you use here.
227
fb4d6ae @semperos Add acknowledgements section to README
authored
228 ## Acknowledgements
229
6907a44 @semperos Add hierarhical query information back into README, reformat links
authored
230 Credits to [mikitebeka/webdriver-clj](https://github.com/mikitebeka/webdriver-clj) for the initial code for this project and many of the low-level wrappers around the Selenium-WebDriver API.
fb4d6ae @semperos Add acknowledgements section to README
authored
231
35e16fd @semperos Add link to Eclipse license in README
authored
232 Many thanks to those who have contributed so far (in nick-alphabetical order):
fb4d6ae @semperos Add acknowledgements section to README
authored
233
9cae71b @semperos Add maxweber to contributors list in README
authored
234 * [maxweber](https://github.com/maxweber) (Max Weber)
fb4d6ae @semperos Add acknowledgements section to README
authored
235 * [RobLally](https://github.com/RobLally) (Rob Lally)
236 * [ulsa](https://github.com/ulsa) (Ulrik Sandberg)
237 * [xeqi](https://github.com/xeqi) (Nelson Morris)
238
239 See Github for an [up-to-date list of contributors](https://github.com/semperos/clj-webdriver/contributors)
240
03ae48a @semperos Initial commit
authored
241 ## License
242
35e16fd @semperos Add link to Eclipse license in README
authored
243 Distributed under the [Eclipse Public License](http://opensource.org/licenses/eclipse-1.0.php), the same as Clojure.
Something went wrong with that request. Please try again.