Skip to content

Commit 67ccba0

Browse files
detrokrosenvold
detro
authored and
krosenvold
committed
IvanDeMarino: README.md now uses GitHub-Markdown.
This still allows great readibility but gives our github-mirror that extra touch. git-svn-id: https://selenium.googlecode.com/svn/trunk@18456 07704840-8298-11de-bf8c-fd130f914ac9
1 parent b24cd00 commit 67ccba0

File tree

1 file changed

+159
-72
lines changed

1 file changed

+159
-72
lines changed

‎README.md

+159-72
Original file line numberDiff line numberDiff line change
@@ -1,142 +1,229 @@
1-
Selenium 2.0 builds with its own build technology that's good for Windows, Linux and Mac.
1+
[Selenium 2.0](http://code.google.com/p/selenium/) builds with
2+
**its own build technology** called
3+
[CrazyFun](http://code.google.com/p/selenium/wiki/CrazyFunBuild) - that's
4+
good for Windows, Linux and Mac.
25

36
# Quick intro
47

5-
In the same directory as this file, do ...
8+
In the same directory as this file, do...
69

7-
./go
10+
```bash
11+
./go
12+
```
813

9-
The order of building modules is determined by the 'go' system itself. If you want to
10-
build an individual module (assuming all dependent modules have previously been build)
11-
try something like ...
14+
The order of building modules is determined by the `go` system itself.
15+
If you want to build an individual module (assuming all dependent modules have
16+
previously been build) try something like:
1217

13-
./go //javascript/atoms:test:run
18+
```bash
19+
./go //javascript/atoms:test:run
20+
```
1421

15-
In this case, javascript/atoms is the module directory, and "test" is a target
16-
in that directory's build.desc file
22+
In this case, `javascript/atoms` is the module directory, and `test` is a target
23+
in that directory's `build.desc` file
1724

18-
As you see 'build targets' scroll past in the log, you may want to run them individually.
19-
'Go' can run them individually, by target name as long as ":run" is appended (see above).
25+
As you see 'build targets' scroll past in the log, you may want to run them
26+
individually. `go` can run them individually, by target name as long as `:run`
27+
is appended (see above).
2028

2129
# Requirements
2230

23-
* Java 6 JDK
24-
* "java" and "jar" on the PATH
31+
* [Java 6 JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
32+
* `java` and `jar` on the PATH
2533

26-
Although the build system is based on rake it's **strongly advised** to rely on the version of JRuby in third_party/ that is invoked by "go". The only developer type who would want to deviate from this is the "build maintainer" who's experimenting with a JRuby upgrade.
34+
Although the build system is based on rake it's **strongly advised** to rely on
35+
the version of JRuby in `third_party/` that is invoked by `go`.
36+
The only developer type who would want to deviate from this is the
37+
"build maintainer" who's experimenting with a JRuby upgrade.
38+
39+
Note that all Selenium Java artefacts are **built with Java 6 (mandatory)**.
40+
Those _will work with any Java >= 6_.
2741

2842
## Optional Requirements
2943

3044
* Python 2.6.x to 2.7 (without this, Python tests will be skipped)
3145

3246
## Internet Explorer Driver
3347

34-
If you plan to compile the IE driver you also need:
48+
If you plan to compile the
49+
[IE driver](http://code.google.com/p/selenium/wiki/InternetExplorerDriver)
50+
you also need:
3551

36-
* Visual Studio 2008
52+
* [Visual Studio 2008](http://www.microsoft.com/visualstudio/en-gb/products/2008-editions)
3753
* 32 and 64 bit cross compilers
3854

39-
The build will work on any platform, but the tests for IE will be skipped silently, if you are not building on Windows.
55+
The build will work on any platform, but the tests for IE will be skipped
56+
silently, if you are not building on Windows.
4057

4158
# Common Tasks
4259

43-
For an express build of the binaries we release run the following from the directory containing the Rakefile:
44-
45-
./go clean release
46-
47-
All build output is placed under the "build" directory. The output can be found under "build/dist". If an error occurs while running this task complaining about a missing Albacore gem, the chances are you're using rvm. If this is the case, switch to the system ruby:
48-
49-
rvm system
50-
51-
Of course, building the entire project can take too long. If you just want to build a single driver, then you can run one of these targets:
52-
53-
./go chrome
54-
./go firefox
55-
./go htmlunit
56-
./go ie
57-
./go opera
58-
59-
As the build progresses, you'll see it report where the build outputs are being placed. Of course, just building isn't enough. We should really be able to run the tests too. Try:
60-
61-
./go test_chrome
62-
./go test_firefox
63-
./go test_htmlunit
64-
./go test_ie
65-
66-
Note that the "test_chrome" target requires that you have the separate chrome driver binary available on your PATH.
60+
For an express build of the binaries we release run the following from the
61+
directory containing the `Rakefile`:
62+
63+
```bash
64+
./go clean release
65+
```
66+
67+
All build output is placed under the `build` directory. The output can be found
68+
under `build/dist`.
69+
If an error occurs while running this task complaining about a missing Albacore
70+
gem, the chances are you're using `rvm`.
71+
If this is the case, switch to the system ruby:
72+
73+
```bash
74+
rvm system
75+
```
76+
77+
Of course, building the entire project can take too long. If you just want to
78+
build a single driver, then you can run one of these targets:
79+
80+
```bash
81+
./go chrome
82+
./go firefox
83+
./go htmlunit
84+
./go ie
85+
./go opera
86+
```
87+
88+
As the build progresses, you'll see it report where the build outputs are being
89+
placed. Of course, just building isn't enough. We should really be able to run
90+
the tests too. Try:
91+
92+
```bash
93+
./go test_chrome
94+
./go test_firefox
95+
./go test_htmlunit
96+
./go test_ie
97+
```
98+
99+
Note that the `test_chrome` target requires that you have the separate
100+
[Chrome Driver](http://code.google.com/p/selenium/wiki/ChromeDriver) binary
101+
available on your `PATH`.
67102

68103
If you are interested in a single language binding, try one of:
69104

70-
./go test_java
71-
./go test_dotnet
72-
./go test_rb
73-
./go test_javascript
105+
```bash
106+
./go test_java
107+
./go test_dotnet
108+
./go test_rb
109+
./go test_javascript
110+
```
74111

75112
To run all the tests just run:
76113

77-
./go test
114+
```bash
115+
./go test
116+
```
78117

79-
This will detect your OS and run all the tests that are known to be stable for every browser that's appropriate to use for all language bindings. This can take a healthy amount of time to run.
118+
This will detect your OS and run all the tests that are known to be stable for
119+
every browser that's appropriate to use for all language bindings.
120+
This can take a healthy amount of time to run.
80121

81122
To run the minimal logical Selenium build:
82123

83-
./go test_javascript test_java
124+
```bash
125+
./go test_javascript test_java
126+
```
84127

85128
To get a list of tasks you could build, do:
86129

87-
./go -T
130+
```bash
131+
./go -T
132+
```
88133

89-
As a side note, none of the developers run tests using cygwin. It is very unlikely that the build will work as expected if you try and use cygwin.
134+
As a side note, **none of the developers** run tests using
135+
[Cygwin](http://www.cygwin.com/).
136+
It is very unlikely that the build will work as expected if you try and use it.
90137

91138
# Tour
92139

93-
The code base is generally segmented around the languages used to write the component. Selenium makes extensive use of Javascript, so let's start there. Working on the javascript is easy. First of all, start the development server:
140+
The code base is generally segmented around the languages used to write the
141+
component. Selenium makes extensive use of JavaScript, so let's start there.
142+
Working on the JavaScript is easy. First of all, start the development server:
94143

95-
./go debug-server
96-
97-
Now navigate to [http://localhost:2310/javascript](http://localhost:2310/javascript) You'll find the contents of the javascript directory being shown. We use the Closure Library for developing much of the javascript, so now navigate to [http://localhost:2310/javascript/atoms/test](http://localhost:2310/javascript/atoms/test)
144+
```bash
145+
./go debug-server
146+
```
98147

99-
The tests in this directory are normal HTML files with names ending with "_test.html". Click on one to load the page and run the test. You can run all the javascript tests using:
148+
Now navigate to [http://localhost:2310/javascript](http://localhost:2310/javascript).
149+
You'll find the contents of the `javascript/` directory being shown.
150+
We use the [Closure Library](https://developers.google.com/closure/library/)
151+
for developing much of the javascript, so now navigate to
152+
[http://localhost:2310/javascript/atoms/test](http://localhost:2310/javascript/atoms/test).
100153

101-
./go test_javascript
154+
The tests in this directory are normal HTML files with names ending with
155+
`_test.html`. Click on one to load the page and run the test. You can run all
156+
the javascript tests using:
157+
158+
```bash
159+
./go test_javascript
160+
```
102161

103162
# Maven POM files
104163

105-
Ignore the Maven POM file present in the same directory. It is only used for releasing to jars to Maven Repository (public or local), and is not considered the main build mechanism.
164+
Ignore the [Maven](http://maven.apache.org/) POM file present in the same
165+
directory. It is only used for releasing to jars to Maven Repository (public or
166+
local), and is not considered the main build mechanism.
167+
168+
Here is the[public Selenium Maven repository](http://repo1.maven.org/maven2/org/seleniumhq/selenium/).
106169

107170
# Build Output
108171

109-
"./go" only makes a top-level "build" directory. Outputs are placed under that relative to the target name. Which is probably best described with an example. For the target:
172+
`./go` only makes a top-level `build` directory. Outputs are placed under that
173+
relative to the target name. Which is probably best described with an example.
174+
For the target:
110175

111-
//java/client/src/org/openqa/selenium:selenium-api
176+
```bash
177+
./go //java/client/src/org/openqa/selenium:selenium-api
178+
```
112179

113180
The output is found under:
114181

115-
build/java/client/src/org/openqa/selenium/selenium-api.jar
182+
```bash
183+
build/java/client/src/org/openqa/selenium/selenium-api.jar
184+
```
116185

117-
If you watch the build, each step should print where its output is going. Java test outputs appear in one of two places: either under build/test_logs for junit or in build/build_log.xml for TestNG tests. If you'd like the build to be chattier, just append "log=true" to the build command line.
186+
If you watch the build, each step should print where its output is going.
187+
Java test outputs appear in one of two places: either under `build/test_logs`
188+
for [JUnit](http://junit.sourceforge.net/) or in `build/build_log.xml`
189+
for [TestNG](http://testng.org/doc/index.html) tests.
190+
If you'd like the build to be chattier, just append `log=true` to the build
191+
command line.
118192

119193
# Help with 'Go'
120194

121195
More general, but basic, help for 'go' ...
122196

123-
./go --help
197+
```bash
198+
./go --help
199+
```
124200

125-
Remember, "go" is just a wrapper around "rake", so you can use the standard rake commands such as "rake -T" to get more information about available targets.
201+
Remember, `go` is just a wrapper around [Rake](http://rake.rubyforge.org/),
202+
so you can use the standard commands such as `rake -T` to get more information
203+
about available targets.
126204

127-
# Maven per se
205+
# Maven _per se_
128206

129-
If it is not clear already, Selenium is not built with Maven, it is built with 'Crazy Fun' though that is invoked with 'go' as outlined above so you do not really have to learn too much about that.
207+
If it is not clear already, Selenium is not built with Maven, it is built with
208+
[Crazy-Fun](http://code.google.com/p/crazy-fun/) though that is invoked with
209+
`go` as outlined above so you do not really have to learn too much about that.
130210

131-
That said, it is possible to relatively quickly build selenium pieces for Maven to use. You are only really going to want to do this when you are testing the cutting-edge of Selenium development (which we welcome) against your application. Here is the quickest way to build and deploy into you local maven repository, while skipping Selenium's own tests.
211+
That said, it is possible to relatively quickly build selenium pieces for Maven
212+
to use. You are only really going to want to do this when you are testing the
213+
cutting-edge of Selenium development (which we welcome) against your
214+
application. Here is the quickest way to build and deploy into you local maven
215+
repository (`~/.m2/repository`), while skipping Selenium's own tests.
132216

133-
./go release
134-
cd maven
135-
mvn clean install
217+
```bash
218+
./go release
219+
cd maven
220+
mvn clean install
221+
```
136222

137-
This sequence will push some seven or so jars into you local Maven repository with something like 'selenium-server-2.0-SNAPSHOT.jar' as the name.
223+
This sequence will push some seven or so jars into you local Maven repository
224+
with something like 'selenium-server-2.0-SNAPSHOT.jar' as the name.
138225

139226
# Last word on building the bits and pieces of Selenium
140227

141-
Refer [Building Web Driver wiki page](http://code.google.com/p/selenium/wiki/BuildingWebDriver)
142-
228+
Refer [Building Web Driver](http://code.google.com/p/selenium/wiki/BuildingWebDriver)
229+
wiki page.

0 commit comments

Comments
 (0)