Skip to content

Commit b1c3650

Browse files
rbrirbri
committed
try to improve documentation
1 parent 1a4438e commit b1c3650

File tree

3 files changed

+206
-108
lines changed

3 files changed

+206
-108
lines changed

‎src/site/site.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959
</menu>
6060
<menu name="Developer docs">
6161
<item name="Getting Latest Code" href="/gettingLatestCode.html"/>
62+
<item name="Development" href="/development.html"/>
6263
<item name="Coding conventions" href="/codingConventions.html"/>
6364
<item name="Submitting bugs" href="/submittingBugs.html"/>
6465
<item name="Submitting JavaScript bugs" href="/submittingJSBugs.html"/>

‎src/site/xdoc/development.xml

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<document>
3+
4+
<properties>
5+
<title>HtmlUnit Development</title>
6+
<author email="[email protected]">Ronald Brill</author>
7+
</properties>
8+
9+
<body>
10+
<section name="Content" id="content">
11+
<macro name="toc">
12+
<param name="section" value="2"/>
13+
<param name="fromDepth" value="0"/>
14+
<param name="toDepth" value="4"/>
15+
</macro>
16+
</section>
17+
18+
<section name="HtmlUnit Development">
19+
<subsection name="Prerequisites">
20+
<p>Before starting, ensure you have the following installed:</p>
21+
<ul>
22+
<li><strong>Java Development Kit (JDK 11)</strong> HtmlUnit is JDK 8 but for running the untit test JDK 11 is required</li>
23+
<li><strong>Eclipse IDE</strong></li>
24+
<li><strong>Maven 3</strong></li>
25+
<li><strong>Git</strong> use your favorite git client</li>
26+
<li><strong>Web Browser</strong>Chrome / Firefox / Edge to check the compatibility</li>
27+
</ul>
28+
</subsection>
29+
30+
<subsection name="Repository Setup and first build">
31+
<h4>Clone the HtmlUnit repository from GitHub</h4>
32+
<source>
33+
git clone https://github.com/HtmlUnit/htmlunit.git
34+
cd htmlunit
35+
</source>
36+
37+
<h4>Compile the project to ensure everything is working correctly</h4>
38+
<source>
39+
mvn clean compile
40+
</source>
41+
42+
<h4>Run some unit tests</h4>
43+
<p>do not run the whole test suite because this takes really long</p>
44+
<source>
45+
mvn test -Dtest=org.htmlunit.javascript.host.dom.*Test
46+
</source>
47+
</subsection>
48+
49+
<subsection name="Eclipse Project Setup">
50+
<h4>Generate Eclipse project files</h4>
51+
<p>use the Maven Eclipse Plugin generate Eclipse project files with source downloads</p>
52+
<source>
53+
mvn eclipse:eclipse -DdownloadSources=true
54+
</source>
55+
<p>then import the Project in Eclipse</p>
56+
<p><code>File → Import → Existing Projects into Workspace</code></p>
57+
58+
<h4>Running Tests from Eclipse</h4>
59+
<p>Usually you would run only some test from Eclipse.</p>
60+
<p>Please have a look at the section 'Running Test with real browsers' below for more options</p>
61+
</subsection>
62+
63+
<subsection name="IntelliJ IDEA Project">
64+
ToDo
65+
</subsection>
66+
67+
<subsection name="Running the Tests from Maven">
68+
<p>Run of the full Test Suite requires significant time (several hours) and resources.
69+
Therfore some profiles are defined to run different parts of the test suite. These
70+
profiels are also used by the various jenkins jobs.</p>
71+
72+
<h4>Run Core test suite</h4>
73+
<p>Run core tests only (faster (~25min), excludes library and huge tests)</p>
74+
<source>
75+
mvn test -P without-library-and-huge-tests -Dgpg.skip -Djava.awt.headless=true
76+
</source>
77+
78+
<h4>Run Library test suite</h4>
79+
<p>Run the test suites from various js libraries (jQuery, prototype, etc.)</p>
80+
<source>
81+
mvn test -P only-library-tests -Dgpg.skip -Djava.awt.headless=true
82+
</source>
83+
84+
<h4>Ports used</h4>
85+
<h5>Test Port Configuration</h5>
86+
<p>
87+
Tests currently assume that port 12345 is free on the machine. If you encounter
88+
<code>java.net.BindException: Address already in use: JVM_Bind</code>, set the
89+
system property <code>htmlunit.test.port</code>:
90+
</p>
91+
<source>
92+
mvn test ... -Dhtmlunit.test.port=10101
93+
</source>
94+
</subsection>
95+
96+
<subsection name="Running Test with real browsers">
97+
<p>The aim of the development of HtmlUnit is to provide as accurate a simulation of the various browsers as possible.
98+
As browsers are constantly evolving, we have to adapt our test assumptions with every update. Therefore (almost)
99+
all tests are implemented in such a way that they can be executed with HtmlUnit as well
100+
as (with the help of Selenium WebDriver) with the supported real browsers.</p>
101+
102+
<p>This behavior is provided by the superclass org.htmlunit.WebDriverTestCase. The test execution can be
103+
switched accordingly with the help of a configuration file.</p>
104+
105+
<p>By default, all tests runing with HtmlUnit, but this behavior can be changed by having a property file named
106+
"{@code test.properties}" in the HtmlUnit root directory.</p>
107+
108+
<p>Sample (remove the part not matching your os)</p>
109+
<source>
110+
browsers=hu
111+
#browsers=hu-ff
112+
#browsers=hu-ff, hu-chrome
113+
#browsers=ff, chrome, edge
114+
115+
ff.bin=/usr/bin/firefox [Unix]
116+
ff-esr.bin=/usr/bin/firefox-esr [Unix]
117+
geckodriver.bin=/usr/bin/driver/geckodriver [Unix]
118+
chrome.bin=/path/to/chromedriver [Unix]
119+
edge.bin=/path/to/chromedriver [Unix]
120+
121+
geckodriver.bin=C:\\path\\to\\geckodriver.exe [Windows]
122+
ff.bin=C:\\path\\to\\Mozilla Firefox\\firefox.exe [Windows]
123+
ff-esr.bin=C:\\path\\to\\Mozilla Firefox ESR\\firefox.exe [Windows]
124+
chrome.bin=C:\\path\\to\\chromedriver.exe [Windows]
125+
edge.bin=C:\\path\\to\\msedgedriver.exe [Windows]
126+
127+
autofix=false
128+
</source>
129+
<p>The file could contain some properties</p>
130+
<ul>
131+
<li>browsers: is a comma separated list contains any combination of
132+
<ul>
133+
<li>hu (for HtmlUnit with all browser versions),</li>
134+
<li>hu-ff,</li>
135+
<li>hu-ff-esr,</li>
136+
<li>hu-chrome,</li>
137+
<li>hu-edge,</li>
138+
<li>ff, (running test using real Firefox),</li>
139+
<li>ff-esr, (running test using real Firefox ESR),</li>
140+
<li>chrome (running test using real Chrome),</li>
141+
<li>edge (running test using real Edge),</li>
142+
</ul>
143+
</li>
144+
145+
<li>chrome.bin (mandatory if it does not exist in the <i>path</i>): is the location of the ChromeDriver binary (see
146+
<a href="https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json">Chrome Driver downloads</a>)</li>
147+
<li>geckodriver.bin (mandatory if it does not exist in the <i>path</i>): is the location of the GeckoDriver binary
148+
(see <a href="https://github.com/mozilla/geckodriver/releases">Gecko Driver Releases</a>)</li>
149+
<li>ff.bin (optional): is the location of the FF binary, in Windows use double back-slashes</li>
150+
<li>ff-esr.bin (optional): is the location of the FF binary, in Windows use double back-slashes</li>
151+
<li>edge.bin (mandatory if it does not exist in the <i>path</i>): is the location of the MicrosoftWebDriver binary
152+
(see <a href="https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/">Microsoft Edge WebDriver downloads</a>)</li>
153+
<li>autofix (optional): if {@code true}, try to automatically fix the real browser expectations,
154+
or add/remove {@code @NotYetImplemented} annotations, use with caution!</li>
155+
</ul>
156+
</subsection>
157+
158+
</section>
159+
</body>
160+
</document>

‎src/site/xdoc/gettingLatestCode.xml

Lines changed: 45 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
<author email="[email protected]">BarnabyCourt</author>
99
<author email="[email protected]">Marc Guillemot</author>
1010
<author email="[email protected]">Ahmed Ashour</author>
11+
<author email="[email protected]">Ronald Brill</author>
1112
</properties>
1213

1314
<body>
@@ -20,124 +21,60 @@
2021

2122
<section name="Latest build">
2223
<p>
23-
You can download the latest build from our <a href="https://jenkins.wetator.org/view/HtmlUnit/">Build server</a>.
24+
<a href="https://jenkins.wetator.org/view/HtmlUnit/">Build server</a>.
2425
</p>
25-
</section>
2626

27-
<section name="Maven snapshot">
2827
<p>
29-
Sonatype OSS repository hosts HtmlUnit snapshot, which is manually updated by the team once in a while.
30-
To use that, you can include the below in your POM:
31-
<source><![CDATA[<project>
32-
...
33-
<repositories>
34-
<repository>
35-
<snapshots>
36-
<enabled>true</enabled>
37-
<updatePolicy>always</updatePolicy>
38-
</snapshots>
39-
<releases>
40-
<enabled>false</enabled>
41-
</releases>
42-
<id>sonatype-nexus-snapshots</id>
43-
<name>Sonatype Nexus Snapshots</name>
44-
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
45-
<layout>default</layout>
46-
</repository>
47-
</repositories>
48-
</project>]]></source>
28+
Sonatype hosts HtmlUnit snapshot, which is manually updated by the team once in a while.
29+
If you need a recent build feel free to contact us.
4930
</p>
50-
</section>
5131

52-
<section name="The source code repository">
53-
<p>
54-
The source code is hosted at <a href="https://github.com/HtmlUnit/htmlunit">GitHub</a>.
55-
</p>
56-
</section>
32+
<subsection name="Maven snapshot">
33+
<p>Add the snapshot repository and dependency to your pom.xml</p>
34+
<source><![CDATA[<project>
35+
<!-- ... -->
36+
<repository>
37+
<name>Central Portal Snapshots</name>
38+
<id>central-portal-snapshots</id>
39+
<url>https://central.sonatype.com/repository/maven-snapshots/</url>
40+
<releases>
41+
<enabled>false</enabled>
42+
</releases>
43+
<snapshots>
44+
<enabled>true</enabled>
45+
</snapshots>
46+
</repository>
5747
58-
<section name="Compiling the code">
59-
<p>
60-
The preferred way to build HtmlUnit is with <a href="http://maven.apache.org">maven 3</a>.
61-
<br/>At least for running the complete test suite a 64 bit JDK is required.
62-
</p>
63-
<source>mvn compile</source>
64-
<p>
65-
This will do an incremental compile of all the code.
66-
</p>
67-
<source>mvn clean compile</source>
68-
<p>
69-
This will do a clean compile of all the code.
70-
</p>
71-
</section>
48+
<!-- ... -->
49+
<dependencies>
50+
<dependency>
51+
<groupId>org.htmlunit</groupId>
52+
<artifactId>htmlunit</artifactId>
53+
<version>4.14.0-SNAPSHOT</version>
54+
</dependency>
55+
<!-- ... -->
56+
</dependencies>
7257
73-
<section name="Dependencies for IDE">
74-
<p>
75-
Usually, you need to get the JARs for your IDE. You can do that by something like:
76-
</p>
77-
<source>Eclipse: right click on the project -> Configure -> Convert to Maven Project</source>
78-
<p>
79-
, alternatively:
80-
</p>
81-
<source>mvn eclipse:eclipse</source>
82-
<p>
83-
or
84-
</p>
85-
<source>mvn idea:idea</source>
86-
<p>
87-
This will create appropriate IDE project.
88-
Note that HtmlUnit is mostly at the bleeding edge, to the extent that an HtmlUnit-local repository
89-
has been created to store snapshots of various dependencies.
90-
</p>
91-
</section>
58+
<!-- ... -->
59+
]]></source>
60+
</subsection>
9261

93-
<section name="Running the tests">
94-
<p>
95-
All the tests are based on <a href="http://www.junit.org/">JUnit</a>.
96-
</p>
97-
<source>mvn test</source>
98-
<p>
99-
This will force a recompile of the java classes if needed.
100-
</p>
101-
<source>mvn test -Dtest=DomNodeTest</source>
102-
<p>
103-
This will run only the specified test class.
104-
</p>
105-
<p>
106-
Tests currently assume that port 12345 is free on the machine,
107-
if you have <tt>java.net.BindException: Address already in use: JVM_Bind</tt>,
108-
then set the system property <code>htmlunit.test.port</code> e.g. <code>-Dhtmlunit.test.port=10101</code>.
109-
<br/>
110-
Additionally class SocksProxyTest requires a SOCKS Proxy running at port 55555.
111-
</p>
112-
</section>
11362

114-
<section name="Packaging">
115-
<source>mvn package</source>
116-
<p>
117-
In the project's target directory you'll able to see the generated jar file with the
118-
name "htmlunit-" followed by the version number.
119-
</p>
120-
<source>mvn source:jar</source>
121-
<p>
122-
This generates a source jar file.
123-
</p>
124-
<source>mvn source:test-jar</source>
125-
<p>
126-
This will generate a jar file of the test sources.
127-
</p>
128-
<source>mvn org.apache.felix:maven-bundle-plugin:bundle</source>
129-
<p>
130-
This will generate an OSGi bundle.
131-
</p>
132-
</section>
63+
<subsection name="Gradle snapshot">
64+
<p>Add the snapshot repository and dependency to your build.gradle</p>
65+
<source><![CDATA[<project>
66+
repositories {
67+
maven { url "https://central.sonatype.com/repository/maven-snapshots/" }
68+
// ...
69+
}
70+
// ...
71+
dependencies {
72+
implementation group: 'org.htmlunit', name: 'htmlunit', version: '4.14.0-SNAPSHOT'
73+
// ...
74+
}
75+
]]></source>
76+
</subsection>
13377

134-
<section name="Forked Rhino (core-js)">
135-
<p>
136-
You can get the source code from
137-
<a href="http://search.maven.org/#browse|1126356811">Maven central repository</a>,
138-
while the repository resides in
139-
<a href="https://github.com/htmlunit">github</a>.
140-
</p>
14178
</section>
14279

14380
</body>

0 commit comments

Comments
 (0)