Skip to content

Commit a413c8d

Browse files
stephenmathiesonstephenmathieson
authored
docs(README): Add deployment section (dequelabs#34)
* docs(README): Add deployment section This patch adds a "deployment" section to the README. This should help out other maintainers rather than leaving them in the dark. Also, my editor formatted the README :) * Update README.md
1 parent 088c6a9 commit a413c8d

File tree

1 file changed

+55
-67
lines changed

1 file changed

+55
-67
lines changed

‎README.md

Lines changed: 55 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -2,89 +2,77 @@
22

33
[![CircleCI](https://circleci.com/gh/dequelabs/axe-selenium-java.svg?style=svg)](https://circleci.com/gh/dequelabs/axe-selenium-java)
44

5-
This example demonstrates how to use aXe to run web accessibility tests in Java
6-
projects with the Selenium browser automation tool and Java development tools.
5+
This example demonstrates how to use aXe to run web accessibility tests in Java projects with the Selenium browser automation tool and Java development tools.
76

87
Selenium integration enables testing of full pages and sites.
98

10-
## Requirements ##
9+
## Requirements
1110

12-
* Chrome must be installed; follow the directions at https://www.google.com/chrome/ to
13-
install it. On Unix, ensure that Chrome is on your path.
14-
* Chrome Driver must be installed; follow the directions at: https://sites.google.com/a/chromium.org/chromedriver/getting-started to install it.
15-
* The Java SE Development Kit must be installed; follow the directions at
16-
http://www.oracle.com/technetwork/java/javase/downloads/index.html to install
17-
it.
18-
* Maven must be installed; follow the directions at http://maven.apache.org/ to
19-
install it. Ensure that it is on your path.
11+
- Chrome must be installed; follow the directions at https://www.google.com/chrome/ to install it. On Unix, ensure that Chrome is on your path.
12+
- Chrome Driver must be installed; follow the directions at: https://sites.google.com/a/chromium.org/chromedriver/getting-started to install it.
13+
- The Java SE Development Kit must be installed; follow the directions at http://www.oracle.com/technetwork/java/javase/downloads/index.html to install it.
14+
- Maven must be installed; follow the directions at http://maven.apache.org/ to install it. Ensure that it is on your path.
2015

21-
## To run the example ##
16+
## To run the example
2217

2318
1. Move to the `selenium-java` directory.
2419
2. Ensure that `axe.min.js` is located in `/src/test/resources`.
2520
3. `node src/test/resources/test-app.js` to start the fixture server.
2621
4. `mvn test` to build and run the JUnit tests that drive Selenium against the fixture.
2722

28-
This should launch an automated Firefox window, load and analyze the
29-
configured web pages, and then pass/fail a JUnit test depending on whether
30-
there are any accessibility violations detected.
23+
This should launch an automated Firefox window, load and analyze the configured web pages, and then pass/fail a JUnit test depending on whether there are any accessibility violations detected.
3124

32-
## To modify the example ##
25+
## To modify the example
3326

34-
To run the example tests on your own web page, change the URL passed to
35-
`driver.get` in `ExampleTest.setUp()`.
27+
To run the example tests on your own web page, change the URL passed to `driver.get` in `ExampleTest.setUp()`.
3628

37-
## To use the AXE helper library in your own tests ##
29+
## To use the AXE helper library in your own tests
3830

3931
Include this library as a test-scoped dependency in your POM:
4032

41-
<dependency>
42-
<groupId>com.deque</groupId>
43-
<artifactId>axe-selenium</artifactId>
44-
<version>2.0</version>
45-
<scope>test</scope>
46-
</dependency>
47-
48-
`axe.js` or `axe.min.js` must be available to your test fixtures as a
49-
`java.net.URL`. The simplest way to do this is to include it in your own
50-
`src.test.resources` and pass `MyTest.class.getResource("/axe.min.js")` to the
51-
`Builder` constructor as demonstrated in the `ExampleTest`.
52-
53-
The `AXE` helper defines three public methods and a nested `Builder` class for
54-
your unit tests.
55-
56-
* `inject` will inject the required script into the page under test and any
57-
iframes. This only needs to be run against a given page once, and `Builder`
58-
will take care of it for you if you use that.
59-
* `report` will pretty-print a list of violations.
60-
* `writeResults` will write the JSON violations list out to a file with the
61-
specified name in the current working directory.
62-
63-
The `Builder` class allows tests to chain configuration and analyze pages. The
64-
constructor takes in a `WebDriver` that has already navigated to the page under
65-
test and a `java.net.URL` pointing to the aXe script; from there, you can set
66-
`options()`, `include()` and `exclude()` selectors, `skipFrames()`, and finally,
67-
`analyze()` the page.
68-
69-
* `options` wires a JSON string to aXe, allowing rules to be toggled on
70-
or off. See the `testAccessibilityWithOptions` unit test for a sample
71-
single-rule execution, and the [axe-core API documentation](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#b-options-parameter)
72-
for full documentation on the options object. The runOnly option with tags
73-
may be of particular interest, allowing aXe to execute all rules with the
74-
specified tag(s).
75-
* `include` adds to the list of included selectors. If you do not call
76-
`include` at all, aXe will run against the entire document.
77-
* `exclude` adds to the list of excluded selectors. Exclusions allow you to
78-
focus scope exactly where you need it, ignoring child elements you don't want
79-
to test.
80-
* `skipFrames` prevents aXe to be recursively injected into all iframes.
81-
* `analyze` executes aXe with any configuration you have previously
82-
defined. If you want to test a single `WebElement`, you may pass it into
83-
`analyze` instead of using `include` and `exclude`.
84-
85-
The aXe documentation should be consulted for more details on customizing and
86-
analyzing calls to `axe.run`.
87-
88-
## Contributing ##
33+
```xml
34+
<dependency>
35+
<groupId>com.deque</groupId>
36+
<artifactId>axe-selenium</artifactId>
37+
<version>2.0</version>
38+
<scope>test</scope>
39+
</dependency>
40+
```
41+
42+
`axe.js` or `axe.min.js` must be available to your test fixtures as a `java.net.URL`. The simplest way to do this is to include it in your own `src.test.resources` and pass `MyTest.class.getResource("/axe.min.js")` to the `Builder` constructor as demonstrated in the `ExampleTest`.
43+
44+
The `AXE` helper defines three public methods and a nested `Builder` class for your unit tests.
45+
46+
- `inject` will inject the required script into the page under test and any iframes. This only needs to be run against a given page once, and `Builder` will take care of it for you if you use that.
47+
- `report` will pretty-print a list of violations.
48+
- `writeResults` will write the JSON violations list out to a file with the specified name in the current working directory.
49+
50+
The `Builder` class allows tests to chain configuration and analyze pages. The constructor takes in a `WebDriver` that has already navigated to the page under test and a `java.net.URL` pointing to the aXe script; from there, you can set `options()`, `include()` and `exclude()` selectors, `skipFrames()`, and finally, `analyze()` the page.
51+
52+
- `options` wires a JSON string to aXe, allowing rules to be toggled on or off. See the `testAccessibilityWithOptions` unit test for a sample single-rule execution, and the [axe-core API documentation](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#b-options-parameter) for full documentation on the options object. The runOnly option with tags may be of particular interest, allowing aXe to execute all rules with the specified tag(s).
53+
- `include` adds to the list of included selectors. If you do not call `include` at all, aXe will run against the entire document.
54+
- `exclude` adds to the list of excluded selectors. Exclusions allow you to focus scope exactly where you need it, ignoring child elements you don't want to test.
55+
- `skipFrames` prevents aXe to be recursively injected into all iframes.
56+
- `analyze` executes aXe with any configuration you have previously defined. If you want to test a single `WebElement`, you may pass it into `analyze` instead of using `include` and `exclude`.
57+
58+
The aXe documentation should be consulted for more details on customizing and analyzing calls to `axe.run`.
59+
60+
## Contributing
8961

9062
In order to contribute, you must accept the [contributor licence agreement](https://cla-assistant.io/dequelabs/axe-selenium-java) (CLA). Acceptance of this agreement will be checked automatically and pull requests without a CLA cannot be merged.
63+
64+
## Deployment (Maintainers Only)
65+
66+
This package is deployed to Maven Central via OSSRH. To deploy this package, follow [these instructions on StackOverflow](https://stackoverflow.com/a/42917618).
67+
68+
Additionally add your OSSRH credentials to your `~/.m2/settings.xml` file as such:
69+
70+
```xml
71+
<servers>
72+
<server>
73+
<id>ossrh</id>
74+
<username>YOUR_OSSRH_JIRA_USERNAME</username>
75+
<password>YOUR_OSSRH_JIRA_PASSWORD</password>
76+
</server>
77+
</servers>
78+
```

0 commit comments

Comments
 (0)