Skip to content

HTTPS clone URL

Subversion checkout URL

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