Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 210 lines (144 sloc) 11.267 kB
597a3f7 @semperos Add Travis png for build status to README
authored
1 # Selenium-WebDriver Support for Clojure [![Build Status](https://secure.travis-ci.org/semperos/clj-webdriver.png)](http://travis-ci.org/semperos/clj-webdriver)
03ae48a @semperos Initial commit
authored
2
4b12ba5 @semperos Add instructions for contributing, branches
authored
3 This is a Clojure library for driving a web browser using Selenium-WebDriver as the backend. For instructions on contributing, see below.
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)
c27578c @semperos Update link to Marginalia docs
authored
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
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
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
16
1b5f218 @semperos Please join the Google group
authored
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
03ae48a @semperos Initial commit
authored
19 ## Usage
20
1507bb5 @semperos Make important points more prominent in README
authored
21 ### Important ###
22
be3ee38 @semperos Update README to reflect new Clojure version
authored
23 * This library uses *Clojure 1.3.0*.
1507bb5 @semperos Make important points more prominent in README
authored
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
27
03ae48a @semperos Initial commit
authored
28 Use/require the library in your code:
29
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
30 ```clj
31 (use 'clj-webdriver.core)
32 ```
03ae48a @semperos Initial commit
authored
33
34 Start up a browser:
35
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
36 ```clj
37 (def b (start :firefox "https://github.com"))
38 ```
03ae48a @semperos Initial commit
authored
39
735c3cb @semperos Update README and source documentation, clean-up remnants of old READ…
authored
40 Here's an example of logging into Github:
03ae48a @semperos Initial commit
authored
41
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
42 ```clj
43 ;; Start the browser and bind it to `b`
44 (def b (start :firefox "https://github.com"))
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
63 (find-it :input {:value #"(?i)log"}) ; use of regular expressions
64 click)
65 ```
03ae48a @semperos Initial commit
authored
66
3a69fae @semperos Add section to README for new quick-fill fn, edit other sections
authored
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
71
3a69fae @semperos Add section to README for new quick-fill fn, edit other sections
authored
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
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
79 ### Finding Elements ###
80
81 The `find-it` and `find-them` functions accept a variety of queries and return one or a seq of all matched elements respectively. Below is a list of query formats these functions accept:
46de941 @semperos Update readme with more examples and better break-down of how to use …
authored
82
d44681e @semperos Update README, more tag options
authored
83 * **HTML Tag as keyword:** Pass in the name of an HTML tag as a keyword (`:div`, `:a`, `:span`, `:img`, etc.) `(find-it :a)` will find the first `<a>` tag on the page. There are also special keywords such as `:*` (match any tag), `:text` (match textfields and textareas), `:window` (to match an open browser window by title or url)
c69c0d2 @semperos Update readme with more details on usage and reformat some things
authored
84 * **HTML Tag plus attributes:** Pass in the name of an HTML tag as a keyword plus some attributes to describe it. `(find-it :a {:class "external"})` will return the first `<a>` tag with a class of "external"
85 * **HTML attributes alone:** You don't have to pass in a tag. `(find-it {:class "external"})` will find the first element of any tag with class "external"
86 * **Multiple HTML attributes:** You can pass in as many attribute-value pairs as you like. `(find-it {:class "external", :text "Moustache"})` will find the first HTML element on the page with both a class of "external" and visible text of "Moustache"
87 * **Regular Expressions:** Instead of looking for an exact match, you can use Java-style regular expressions to find elements. `(find-it :a {:class #"exter"})` will find the first `<a>` tag with a class which matches the regular expression `#"exter"`. You can also use regexes in the final position of an ancestry-based query (see below).
d44681e @semperos Update README, more tag options
authored
88 * **Ancestry-based queries:** This library provides a pure-Clojure mechanism for finding an element based on parent elements. `(find-it [:div {:id "content"}, :a {:class "external"}])` will find the first `<a>` tag with a class of "external" that is located within the `<div>` with id "content". This is equivalent to the XPath `//div[@id='content']//a[@class='external']`. You can also include regular expressions in the final attribute-value map which you supply. (*Note: Due to issues of ambiguity and in order not to reinvent the wheel any further, applying regexes higher up the query is not supported and will cause an exception. In addition, none of the "semantic" tags such as `:button*`, `:radio`, `:checkbox`, `:textfield`, etc. that do not map directly to HTML tags are not supported. If you need more advanced querying, use XPath or CSS selectors directly.)*
0565378 @semperos Update readme to accurately reflect how :xpath and :css are handled
authored
89 * **XPath and CSS Selectors:** You can use the `:xpath` and `:css` attributes to use such queries in place of simple HTML attributes. If you use one of these attributes, you shouldn't use any others, as they will be ignored (e.g. `{:xpath "//a", :class "external"}` will only utilize the xpath `//a`). `(find-it {:xpath "//a[@class='external']"})` will return the first `<a>` tag with a class of "external"
46de941 @semperos Update readme with more examples and better break-down of how to use …
authored
90
c36bba7 @semperos Update alternative find-it functions to take a map of attr-val just l…
authored
91 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:
92
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
93 ```clj
94 (-> b
95 (find-it :a) ; assuming its the first <a> on the page
96 click)
97
98 (-> b
99 (find-it {:id "contact-link"}) ; :id is unique, so only one is needed
100 click)
101
102 (-> b
103 (find-it {:class "menu-item", :name "contact"}) ; use multiple attributes
104 click)
105
106 (-> b
107 (find-it :a {:class "menu-item", :name "contact"}) ; specify tag
108 click)
109
110 (-> b
111 (find-it :a {:text "Contact Us"}) ; special :text attribute, uses XPath's
112 click) ; text() function to find the element
113
114 (-> b
115 (find-it :a {:class #"(?i)menu-"}) ; use Java-style regular
116 click) ; expressions
117
118 (-> b
119 (find-it [:div {:id "content"}, :a {:id "contact-link"}]) ; hierarchical/ancestry-based query
120 click) ; equivalent to
121 ; //div[@id='content']//a[@id='contact-link']
122
123 (-> b
124 (find-it [:div {:id "content"}, :a {}]) ; ancestry-based query, tag with
125 click) ; no attributes (empty map required)
126
127 (-> b
128 (find-it {:xpath "//a[@id='contact-link']"}) ; XPath query
129 click)
c36bba7 @semperos Update alternative find-it functions to take a map of attr-val just l…
authored
130
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
131 (-> b
132 (find-it {:css "a#contact-link"}) ; CSS selector
133 click)
134 ```
b8fea8d @semperos Update readme with more details, remove 'low level' example
authored
135
735c3cb @semperos Update README and source documentation, clean-up remnants of old READ…
authored
136 So, to describe the general pattern of interacting with the page:
137
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
138 ```clj
139 (-> browser-instance
140 (find-it options)
141 (do-something-with-the-element))
142 ```
03ae48a @semperos Initial commit
authored
143
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
144 ### Firefox Functionality
145
146 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]:
147
88cc5b5 @semperos Update README to use Github-style md for code blocks
authored
148 ```clj
149 (use 'clj-webdriver.core)
150 (require '[clj-webdriver.firefox :as ff])
151
152 (def b (new-driver :firefox
153 (doto (ff/new-profile)
154 ;; Enable Firebug
155 (ff/enable-extension "/path/to/extensions/firebug.xpi")))
156
157 ;; Auto-download certain file types to a specific folder
158 (ff/set-preferences {:browser.download.dir "C:/Users/semperos/Desktop",
159 :browser.download.folderList 2
160 :browser.helperApps.neverAsk.saveToDisk "application/pdf"})))
161 ```
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
162
aacdcb4 @semperos Add information about Grid support to the README
authored
163 ### Grid Support ###
164
165 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.
166
167 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.
168
169 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
170
4b12ba5 @semperos Add instructions for contributing, branches
authored
171 ## Contributing ##
172
173 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.
174
175 If you want to fix a bug in the **current release**, please pull against the appropriate branch for the current minor version, e.g. 0.4.x.
176
ed9aefb @semperos Update README with information about running test suite
authored
177 ## Running Tests
178
32f5593 @semperos Update docs for running tests
authored
179 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
180
32f5593 @semperos Update docs for running tests
authored
181 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
182
0b76354 @semperos Add back part of documentation that gives instructions for starting u…
authored
183 *Note:* If you just want to run the example app that clj-webdriver uses for its testing purposes, do the following:
184
185 * Open a terminal and run `lein repl` or `lein swank` at the root of this project
186 * Evaluate `(use 'clj-webdriver.test.example-app.core 'ring.adapter.jetty)`
187 * 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.
188
fb4d6ae @semperos Add acknowledgements section to README
authored
189 ## Acknowledgements
190
191 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.
192
35e16fd @semperos Add link to Eclipse license in README
authored
193 Many thanks to those who have contributed so far (in nick-alphabetical order):
fb4d6ae @semperos Add acknowledgements section to README
authored
194
9cae71b @semperos Add maxweber to contributors list in README
authored
195 * [maxweber](https://github.com/maxweber) (Max Weber)
fb4d6ae @semperos Add acknowledgements section to README
authored
196 * [RobLally](https://github.com/RobLally) (Rob Lally)
197 * [ulsa](https://github.com/ulsa) (Ulrik Sandberg)
198 * [xeqi](https://github.com/xeqi) (Nelson Morris)
199
200 See Github for an [up-to-date list of contributors](https://github.com/semperos/clj-webdriver/contributors)
201
03ae48a @semperos Initial commit
authored
202 ## License
203
35e16fd @semperos Add link to Eclipse license in README
authored
204 Distributed under the [Eclipse Public License](http://opensource.org/licenses/eclipse-1.0.php), the same as Clojure.
03ae48a @semperos Initial commit
authored
205
206 [webdriver-orig]: https://github.com/mikitebeka/webdriver-clj
ed9aefb @semperos Update README with information about running test suite
authored
207 [ring-github]: https://github.com/mmcgrana/ring
208 [moustache-github]: https://github.com/cgrand/moustache
5e8d682 @semperos Add info on Firefox-specific functionality and provide code examples
authored
209 [wd-ruby-bindings]: http://code.google.com/p/selenium/wiki/RubyBindings
Something went wrong with that request. Please try again.