Skip to content
Newer
Older
100644 234 lines (156 sloc) 9.46 KB
4a86f36 @semperos Take out Travis status image, build breaking due to server configurat…
authored Jan 4, 2012
1 # Selenium-WebDriver Support for Clojure #
03ae48a @semperos Initial commit
authored Mar 11, 2011
2
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
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).
03ae48a @semperos Initial commit
authored Mar 11, 2011
4
3296292 @semperos Update README with another Selenium-WebDriver link, split up resource…
authored Nov 29, 2011
5 **clj-webdriver Resources**
6
c38290a @semperos Add primary links for this project's resources to the README
authored Aug 11, 2011
7 * [Project Wiki](https://github.com/semperos/clj-webdriver/wiki)
c27578c @semperos Update link to Marginalia docs
authored Nov 2, 2011
8 * [Marginalia Documentation (v0.4.0)](http://semperos.github.com/clj-webdriver/uberdoc-latest.html)
c38290a @semperos Add primary links for this project's resources to the README
authored Aug 11, 2011
9 * [Google Group](https://groups.google.com/forum/#!forum/clj-webdriver)
10 * [Issue Queue](https://github.com/semperos/clj-webdriver/issues)
3296292 @semperos Update README with another Selenium-WebDriver link, split up resource…
authored Nov 29, 2011
11
12 **Selenium-WebDriver Resources**
13
14 * [API Javadoc](http://selenium.googlecode.com/svn/trunk/docs/api/java/index.html)
15 * [Changelog](http://code.google.com/p/selenium/source/browse/trunk/java/CHANGELOG)
c38290a @semperos Add primary links for this project's resources to the README
authored Aug 11, 2011
16
1b5f218 @semperos Please join the Google group
authored Nov 3, 2011
17 **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!
18
4a86f36 @semperos Take out Travis status image, build breaking due to server configurat…
authored Jan 4, 2012
19 ## Usage ##
03ae48a @semperos Initial commit
authored Mar 11, 2011
20
1507bb5 @semperos Make important points more prominent in README
authored Aug 10, 2011
21 ### Important ###
22
be3ee38 @semperos Update README to reflect new Clojure version
authored Sep 26, 2011
23 * This library uses *Clojure 1.3.0*.
1507bb5 @semperos Make important points more prominent in README
authored Aug 10, 2011
24 * You *must* add the java.net Maven repository to your own `project.clj` when using this library (for example: `:repositories {"java-dot-net" "http://download.java.net/maven/2"}`). The JNA jars required by the latest Selenium-WebDriver release are only available there.
25
26 ### Quickstart ###
01d7b2d @semperos Fix phirsch's issue with WindowHandle not being found due to namespac…
authored May 13, 2011
27
03ae48a @semperos Initial commit
authored Mar 11, 2011
28 Use/require the library in your code:
29
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
30 ```clj
31 (use 'clj-webdriver.core)
32 ```
03ae48a @semperos Initial commit
authored Mar 11, 2011
33
34 Start up a browser:
35
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
36 ```clj
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
37 (def b (start {:browser :firefox} "https://github.com"))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
38 ```
03ae48a @semperos Initial commit
authored Mar 11, 2011
39
735c3cb @semperos Update README and source documentation, clean-up remnants of old READ…
authored Mar 12, 2011
40 Here's an example of logging into Github:
03ae48a @semperos Initial commit
authored Mar 11, 2011
41
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
42 ```clj
43 ;; Start the browser and bind it to `b`
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
44 (def b (start {:browser :firefox} "https://github.com"))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
45
46 ;; Click "Login" link
47 (-> b
48 (find-it {:text "Login"})
49 click)
50
51 ;; Input username/email into the "Login or Email" field
52 (-> b
53 (find-it {:class "text", :name "login"}) ; use multiple attributes
54 (input-text "username"))
55
56 ;; Input password into the "Password" field
57 (-> b
58 (find-it {:xpath "//input[@id='password']"}) ; :xpath and :css options
59 (input-text "password"))
60
61 ;; Click the "Log in" button"
62 (-> b
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
63 (find-it {:tag :input, :value #"(?i)log"}) ; use of regular expressions
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
64 click)
65 ```
03ae48a @semperos Initial commit
authored Mar 11, 2011
66
3a69fae @semperos Add section to README for new quick-fill fn, edit other sections
authored Aug 18, 2011
67 Filling out the form can been accomplished more compactly using `clj-webdriver.form-helpers/quick-fill` as follows:
68
69 ```clj
70 (require '[clj-webdriver.form-helpers :as form])
b8fea8d @semperos Update readme with more details, remove 'low level' example
authored Mar 11, 2011
71
3a69fae @semperos Add section to README for new quick-fill fn, edit other sections
authored Aug 18, 2011
72 (form/quick-fill b [{{:class "text", :name "login"} "username"}
73 {{:xpath "//input[@id='password']"} "password"}
74 {{:value #"(?i)log"} click}])
75 ```
76
af54249 @semperos Update README
authored Oct 19, 2011
77 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).
78
3a69fae @semperos Add section to README for new quick-fill fn, edit other sections
authored Aug 18, 2011
79 ### Finding Elements ###
80
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
81 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 Mar 14, 2011
82
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
83 #### Attribute-Value Map ####
84
85 The attribute-value map (`attr-val`) can consist of HTML attributes, or can designate an XPath or CSS query:
86
87 ```clj
88 (find-it driver {:class "foo"})
89 (find-it driver {:tag :a, :class "bar"})
90
91 (find-it driver {:xpath "//a[@class='foo']"})
92 (find-it driver {:css "a.bar"})
93 ```
94
95 If the `:xpath` or `:css` options are used, everything else in the `attr-val` map is ignored.
96
97 ##### Special Tags #####
98
99 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.
100
101 Here are all the special tags in action:
102
103 ```clj
104 (find-it driver {:tag :radio})
105 ;=> (find-it driver {:tag :input, :type "radio"})
106
107 (find-it driver {:tag :checkbox})
108 ;=> (find-it driver {:tag :input, :type "checkbox"})
109
110 (find-it driver {:tag :textfield})
111 ;=> (find-it driver {:tag :input, :type "text"})
112
113 (find-it driver {:tag :password})
114 ;=> (find-it driver {:tag :input, :type "password"})
115
116 (find-it driver {:tag :filefield})
117 ;=> (find-it driver {:tag :input, :type "file"})
118
119 (find-it driver {:tag :button*})
120 ```
121
122 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 Mar 14, 2011
123
c36bba7 @semperos Update alternative find-it functions to take a map of attr-val just l…
authored Mar 12, 2011
124 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:
125
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
126 ```clj
127 (-> b
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
128 (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 Jul 14, 2011
129 click)
130
131 (-> b
132 (find-it {:id "contact-link"}) ; :id is unique, so only one is needed
133 click)
134
135 (-> b
136 (find-it {:class "menu-item", :name "contact"}) ; use multiple attributes
137 click)
138
139 (-> b
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
140 (find-it {:tag :a, :class "menu-item", :name "contact"}) ; specify tag
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
141 click)
142
143 (-> b
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
144 (find-it {:tag :a, :text "Contact Us"}) ; special :text attribute, uses XPath's
145 click) ; text() function to find the element
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
146
147 (-> b
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
148 (find-it {:tag :a, :class #"(?i)menu-"}) ; use Java-style regular
149 click) ; expressions
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
150
151 (-> b
152 (find-it {:xpath "//a[@id='contact-link']"}) ; XPath query
153 click)
c36bba7 @semperos Update alternative find-it functions to take a map of attr-val just l…
authored Mar 12, 2011
154
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
155 (-> b
156 (find-it {:css "a#contact-link"}) ; CSS selector
157 click)
158 ```
b8fea8d @semperos Update readme with more details, remove 'low level' example
authored Mar 11, 2011
159
735c3cb @semperos Update README and source documentation, clean-up remnants of old READ…
authored Mar 12, 2011
160 So, to describe the general pattern of interacting with the page:
161
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
162 ```clj
163 (-> browser-instance
164 (find-it options)
165 (do-something-with-the-element))
166 ```
03ae48a @semperos Initial commit
authored Mar 11, 2011
167
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored Mar 15, 2011
168 ### Firefox Functionality
169
170 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]:
171
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
172 ```clj
173 (use 'clj-webdriver.core)
174 (require '[clj-webdriver.firefox :as ff])
175
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
176 (def b (new-driver {:browser :firefox,
177 :profile (doto (ff/new-profile)
178 ;; Enable Firebug
179 (ff/enable-extension "/path/to/extensions/firebug.xpi")))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
180
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
181 ;; Auto-download certain file types to a specific folder
182 (ff/set-preferences {:browser.download.dir "C:/Users/semperos/Desktop",
183 :browser.download.folderList 2
184 :browser.helperApps.neverAsk.saveToDisk "application/pdf"})))
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored Jul 14, 2011
185 ```
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored Mar 15, 2011
186
aacdcb4 @semperos Add information about Grid support to the README
authored Oct 5, 2011
187 ### Grid Support ###
188
189 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.
190
191 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.
192
193 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 Mar 15, 2011
194
4b12ba5 @semperos Add instructions for contributing, branches
authored Nov 3, 2011
195 ## Contributing ##
196
197 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.
198
f6878e0 @semperos Update README with new syntax
authored Jan 4, 2012
199 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 Nov 3, 2011
200
ed9aefb @semperos Update README with information about running test suite
authored Mar 11, 2011
201 ## Running Tests
202
32f5593 @semperos Update docs for running tests
authored Aug 18, 2011
203 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 Mar 11, 2011
204
32f5593 @semperos Update docs for running tests
authored Aug 18, 2011
205 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 Mar 11, 2011
206
0b76354 @semperos Add back part of documentation that gives instructions for starting u…
authored Oct 24, 2011
207 *Note:* If you just want to run the example app that clj-webdriver uses for its testing purposes, do the following:
208
209 * Open a terminal and run `lein repl` or `lein swank` at the root of this project
210 * Evaluate `(use 'clj-webdriver.test.example-app.core 'ring.adapter.jetty)`
211 * 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.
212
fb4d6ae @semperos Add acknowledgements section to README
authored Sep 26, 2011
213 ## Acknowledgements
214
215 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.
216
35e16fd @semperos Add link to Eclipse license in README
authored Nov 1, 2011
217 Many thanks to those who have contributed so far (in nick-alphabetical order):
fb4d6ae @semperos Add acknowledgements section to README
authored Sep 26, 2011
218
9cae71b @semperos Add maxweber to contributors list in README
authored Nov 3, 2011
219 * [maxweber](https://github.com/maxweber) (Max Weber)
fb4d6ae @semperos Add acknowledgements section to README
authored Sep 26, 2011
220 * [RobLally](https://github.com/RobLally) (Rob Lally)
221 * [ulsa](https://github.com/ulsa) (Ulrik Sandberg)
222 * [xeqi](https://github.com/xeqi) (Nelson Morris)
223
224 See Github for an [up-to-date list of contributors](https://github.com/semperos/clj-webdriver/contributors)
225
03ae48a @semperos Initial commit
authored Mar 11, 2011
226 ## License
227
35e16fd @semperos Add link to Eclipse license in README
authored Nov 1, 2011
228 Distributed under the [Eclipse Public License](http://opensource.org/licenses/eclipse-1.0.php), the same as Clojure.
03ae48a @semperos Initial commit
authored Mar 11, 2011
229
230 [webdriver-orig]: https://github.com/mikitebeka/webdriver-clj
ed9aefb @semperos Update README with information about running test suite
authored Mar 11, 2011
231 [ring-github]: https://github.com/mmcgrana/ring
232 [moustache-github]: https://github.com/cgrand/moustache
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored Mar 15, 2011
233 [wd-ruby-bindings]: http://code.google.com/p/selenium/wiki/RubyBindings
Something went wrong with that request. Please try again.