Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 195 lines (136 sloc) 10.32 kb
597a3f7 Daniel Gregoire 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 Daniel Gregoire Initial commit
authored
2
fb4d6ae Daniel Gregoire Add acknowledgements section to README
authored
3 This is a Clojure library for driving a web browser using Selenium-WebDriver as the backend.
03ae48a Daniel Gregoire Initial commit
authored
4
c38290a Daniel Gregoire Add primary links for this project's resources to the README
authored
5 * [Project Wiki](https://github.com/semperos/clj-webdriver/wiki)
41b7ed1 Daniel Gregoire Add version to link to marginalia docs
authored
6 * [Marginalia Documentation (v0.3.0)](http://techylinguist.com/project-static/clj-webdriver/uberdoc.html)
c38290a Daniel Gregoire 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 Daniel Gregoire Add link to Selenium-WebDriver javadoc
authored
9 * [Selenium-WebDriver Javadoc](http://selenium.googlecode.com/svn/trunk/docs/api/java/index.html)
c38290a Daniel Gregoire Add primary links for this project's resources to the README
authored
10
03ae48a Daniel Gregoire Initial commit
authored
11 ## Usage
12
1507bb5 Daniel Gregoire Make important points more prominent in README
authored
13 ### Important ###
14
be3ee38 Daniel Gregoire Update README to reflect new Clojure version
authored
15 * This library uses *Clojure 1.3.0*.
1507bb5 Daniel Gregoire Make important points more prominent in README
authored
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 ###
01d7b2d Daniel Gregoire Fix phirsch's issue with WindowHandle not being found due to namespace w...
authored
19
03ae48a Daniel Gregoire Initial commit
authored
20 Use/require the library in your code:
21
88cc5b5 Daniel Gregoire Update README to use Github-style md for code blocks
authored
22 ```clj
23 (use 'clj-webdriver.core)
24 ```
03ae48a Daniel Gregoire Initial commit
authored
25
26 Start up a browser:
27
88cc5b5 Daniel Gregoire Update README to use Github-style md for code blocks
authored
28 ```clj
29 (def b (start :firefox "https://github.com"))
30 ```
03ae48a Daniel Gregoire Initial commit
authored
31
735c3cb Daniel Gregoire Update README and source documentation, clean-up remnants of old README ...
authored
32 Here's an example of logging into Github:
03ae48a Daniel Gregoire Initial commit
authored
33
88cc5b5 Daniel Gregoire Update README to use Github-style md for code blocks
authored
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 ```
03ae48a Daniel Gregoire Initial commit
authored
58
3a69fae Daniel Gregoire Add section to README for new quick-fill fn, edit other sections
authored
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])
b8fea8d Daniel Gregoire Update readme with more details, remove 'low level' example
authored
63
3a69fae Daniel Gregoire Add section to README for new quick-fill fn, edit other sections
authored
64 (form/quick-fill b [{{:class "text", :name "login"} "username"}
65 {{:xpath "//input[@id='password']"} "password"}
66 {{:value #"(?i)log"} click}])
67 ```
68
af54249 Daniel Gregoire Update README
authored
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
3a69fae Daniel Gregoire Add section to README for new quick-fill fn, edit other sections
authored
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:
46de941 Daniel Gregoire Update readme with more examples and better break-down of how to use fin...
authored
74
d44681e Daniel Gregoire Update README, more tag options
authored
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)
c69c0d2 Daniel Gregoire Update readme with more details on usage and reformat some things
authored
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).
d44681e Daniel Gregoire Update README, more tag options
authored
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.)*
0565378 Daniel Gregoire Update readme to accurately reflect how :xpath and :css are handled
authored
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"
46de941 Daniel Gregoire Update readme with more examples and better break-down of how to use fin...
authored
82
c36bba7 Daniel Gregoire Update alternative find-it functions to take a map of attr-val just like...
authored
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
88cc5b5 Daniel Gregoire Update README to use Github-style md for code blocks
authored
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)
c36bba7 Daniel Gregoire Update alternative find-it functions to take a map of attr-val just like...
authored
122
88cc5b5 Daniel Gregoire Update README to use Github-style md for code blocks
authored
123 (-> b
124 (find-it {:css "a#contact-link"}) ; CSS selector
125 click)
126 ```
b8fea8d Daniel Gregoire Update readme with more details, remove 'low level' example
authored
127
735c3cb Daniel Gregoire Update README and source documentation, clean-up remnants of old README ...
authored
128 So, to describe the general pattern of interacting with the page:
129
88cc5b5 Daniel Gregoire Update README to use Github-style md for code blocks
authored
130 ```clj
131 (-> browser-instance
132 (find-it options)
133 (do-something-with-the-element))
134 ```
03ae48a Daniel Gregoire Initial commit
authored
135
5e8d682 Daniel Gregoire Add info on Firefox-specific functionality and provide code examples
authored
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
88cc5b5 Daniel Gregoire Update README to use Github-style md for code blocks
authored
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 ```
5e8d682 Daniel Gregoire Add info on Firefox-specific functionality and provide code examples
authored
154
aacdcb4 Daniel Gregoire Add information about Grid support to the README
authored
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).
5e8d682 Daniel Gregoire Add info on Firefox-specific functionality and provide code examples
authored
162
ed9aefb Daniel Gregoire Update README with information about running test suite
authored
163 ## Running Tests
164
32f5593 Daniel Gregoire Update docs for running tests
authored
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.
ed9aefb Daniel Gregoire Update README with information about running test suite
authored
166
32f5593 Daniel Gregoire Update docs for running tests
authored
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.
ed9aefb Daniel Gregoire Update README with information about running test suite
authored
168
0b76354 Daniel Gregoire Add back part of documentation that gives instructions for starting up t...
authored
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
fb4d6ae Daniel Gregoire Add acknowledgements section to README
authored
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
179 Many thanks to those who have contributed so far (in nick alphabetical order):
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
03ae48a Daniel Gregoire Initial commit
authored
187 ## License
188
189 Distributed under the Eclipse Public License, the same as Clojure.
190
191 [webdriver-orig]: https://github.com/mikitebeka/webdriver-clj
ed9aefb Daniel Gregoire Update README with information about running test suite
authored
192 [ring-github]: https://github.com/mmcgrana/ring
193 [moustache-github]: https://github.com/cgrand/moustache
5e8d682 Daniel Gregoire Add info on Firefox-specific functionality and provide code examples
authored
194 [wd-ruby-bindings]: http://code.google.com/p/selenium/wiki/RubyBindings
Something went wrong with that request. Please try again.