Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 239 lines (160 sloc) 9.883 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
96 ##### Special Tags #####
97
98 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.
99
100 Here are all the special tags in action:
101
102 ```clj
103 (find-it driver {:tag :radio})
104 ;=> (find-it driver {:tag :input, :type "radio"})
105
106 (find-it driver {:tag :checkbox})
107 ;=> (find-it driver {:tag :input, :type "checkbox"})
108
109 (find-it driver {:tag :textfield})
110 ;=> (find-it driver {:tag :input, :type "text"})
111
112 (find-it driver {:tag :password})
113 ;=> (find-it driver {:tag :input, :type "password"})
114
115 (find-it driver {:tag :filefield})
116 ;=> (find-it driver {:tag :input, :type "file"})
117
118 (find-it driver {:tag :button*})
119 ```
120
121 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
122
c36bba7 @semperos Update alternative find-it functions to take a map of attr-val just l…
authored
123 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:
124
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
125 ```clj
126 (-> b
f6878e0 @semperos Update README with new syntax
authored
127 (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
128 click)
129
130 (-> b
131 (find-it {:id "contact-link"}) ; :id is unique, so only one is needed
132 click)
133
134 (-> b
135 (find-it {:class "menu-item", :name "contact"}) ; use multiple attributes
136 click)
137
138 (-> b
f6878e0 @semperos Update README with new syntax
authored
139 (find-it {:tag :a, :class "menu-item", :name "contact"}) ; specify tag
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
140 click)
141
142 (-> b
f6878e0 @semperos Update README with new syntax
authored
143 (find-it {:tag :a, :text "Contact Us"}) ; special :text attribute, uses XPath's
144 click) ; text() function to find the element
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
145
146 (-> b
f6878e0 @semperos Update README with new syntax
authored
147 (find-it {:tag :a, :class #"(?i)menu-"}) ; use Java-style regular
148 click) ; expressions
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
149
150 (-> b
151 (find-it {:xpath "//a[@id='contact-link']"}) ; XPath query
152 click)
c36bba7 @semperos Update alternative find-it functions to take a map of attr-val just l…
authored
153
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
154 (-> b
155 (find-it {:css "a#contact-link"}) ; CSS selector
156 click)
157 ```
b8fea8d @semperos Update readme with more details, remove 'low level' example
authored
158
735c3cb @semperos Update README and source documentation, clean-up remnants of old READ…
authored
159 So, to describe the general pattern of interacting with the page:
160
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
161 ```clj
162 (-> browser-instance
163 (find-it options)
164 (do-something-with-the-element))
165 ```
03ae48a @semperos Initial commit
authored
166
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
167 ### Firefox Functionality
168
169 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][wd-ruby-bindings]:
170
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
171 ```clj
172 (use 'clj-webdriver.core)
173 (require '[clj-webdriver.firefox :as ff])
174
f6878e0 @semperos Update README with new syntax
authored
175 (def b (new-driver {:browser :firefox,
176 :profile (doto (ff/new-profile)
177 ;; Enable Firebug
178 (ff/enable-extension "/path/to/extensions/firebug.xpi")))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
179
f6878e0 @semperos Update README with new syntax
authored
180 ;; Auto-download certain file types to a specific folder
181 (ff/set-preferences {:browser.download.dir "C:/Users/semperos/Desktop",
182 :browser.download.folderList 2
c33576b @semperos Correct Clojure syntax in README example for Firefox functionality
authored
183 :browser.helperApps.neverAsk.saveToDisk "application/pdf"})}))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
184 ```
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
185
aacdcb4 @semperos Add information about Grid support to the README
authored
186 ### Grid Support ###
187
188 If you already have a Selenium-WebDriver Grid (2) setup in place, you can now leverage the functions in `clj-webdriver.grid` to run your tests via the Grid.
189
190 At this point, `clj-webdriver.grid` has two functions, `new-driver-on-grid` and `start-on-grid` which are Grid equivalents for the `clj-webdriver.core` functions named `new-driver` and `start` respectively. You simply replace your call to `start` or `new-driver` with `start-on-grid` or `new-driver-on-grid` and your tests will run on the Grid.
191
192 For more information about configuring your Grid hub and nodes, 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
193
4b12ba5 @semperos Add instructions for contributing, branches
authored
194 ## Contributing ##
195
196 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.
197
f6878e0 @semperos Update README with new syntax
authored
198 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
199
ed9aefb @semperos Update README with information about running test suite
authored
200 ## Running Tests
201
32f5593 @semperos Update docs for running tests
authored
202 The namespace `clj-webdriver.test.example-app.core` contains a [Ring][ring-github] app (routing by [Moustache][moustache-github]) that acts as the "control application" for this project's test suite.
ed9aefb @semperos Update README with information about running test suite
authored
203
32f5593 @semperos Update docs for running tests
authored
204 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
205
28aa16e @semperos Update readme with how to run tests for individual browsers
authored
206 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:
207
208 ```
209 lein test clj-webdriver.test.firefox
210 ```
211
0b76354 @semperos Add back part of documentation that gives instructions for starting u…
authored
212 *Note:* If you just want to run the example app that clj-webdriver uses for its testing purposes, do the following:
213
214 * Open a terminal and run `lein repl` or `lein swank` at the root of this project
215 * Evaluate `(use 'clj-webdriver.test.example-app.core 'ring.adapter.jetty)`
216 * 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.
217
fb4d6ae @semperos Add acknowledgements section to README
authored
218 ## Acknowledgements
219
220 Credits to [mikitebeka/webdriver-clj][webdriver-orig] for the initial code for this project and many of the low-level wrappers around the Selenium-WebDriver API.
221
35e16fd @semperos Add link to Eclipse license in README
authored
222 Many thanks to those who have contributed so far (in nick-alphabetical order):
fb4d6ae @semperos Add acknowledgements section to README
authored
223
9cae71b @semperos Add maxweber to contributors list in README
authored
224 * [maxweber](https://github.com/maxweber) (Max Weber)
fb4d6ae @semperos Add acknowledgements section to README
authored
225 * [RobLally](https://github.com/RobLally) (Rob Lally)
226 * [ulsa](https://github.com/ulsa) (Ulrik Sandberg)
227 * [xeqi](https://github.com/xeqi) (Nelson Morris)
228
229 See Github for an [up-to-date list of contributors](https://github.com/semperos/clj-webdriver/contributors)
230
03ae48a @semperos Initial commit
authored
231 ## License
232
35e16fd @semperos Add link to Eclipse license in README
authored
233 Distributed under the [Eclipse Public License](http://opensource.org/licenses/eclipse-1.0.php), the same as Clojure.
03ae48a @semperos Initial commit
authored
234
235 [webdriver-orig]: https://github.com/mikitebeka/webdriver-clj
ed9aefb @semperos Update README with information about running test suite
authored
236 [ring-github]: https://github.com/mmcgrana/ring
237 [moustache-github]: https://github.com/cgrand/moustache
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
238 [wd-ruby-bindings]: http://code.google.com/p/selenium/wiki/RubyBindings
Something went wrong with that request. Please try again.