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