Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mike10004/xvfb-manager-java
Library that manages an xvfb process and a JUnit rule that employs the library.
https://github.com/mike10004/xvfb-manager-java
java junit selenium xvfb
Last synced: 2 months ago
JSON representation
Library that manages an xvfb process and a JUnit rule that employs the library.
- Host: GitHub
- URL: https://github.com/mike10004/xvfb-manager-java
- Owner: mike10004
- License: mit
- Created: 2016-11-07T16:15:22.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2021-04-26T16:19:54.000Z (over 3 years ago)
- Last Synced: 2024-10-04T16:46:06.925Z (3 months ago)
- Topics: java, junit, selenium, xvfb
- Language: Java
- Size: 361 KB
- Stars: 11
- Watchers: 2
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/mike10004/xvfb-manager-java)
[](https://repo1.maven.org/maven2/com/github/mike10004/xvfb-manager-parent/)
xvfb-manager
============
Java Xvfb manager. A library for managing an Xvfb process and a JUnit
rule for using that library in unit or integration tests.
Quickstart - Core Library
-------------------------
### Maven
com.github.mike10004
xvfb-manager
0.14
### Code
XvfbManager manager = new XvfbManager();
try (final XvfbController controller = manager.start()) {
controller.waitUntilReady();
// start a graphical program on a different thread
Future processFuture = Executors.newSingleThreadExecutor().submit(new Callable(){
@Override
public Process call() throws Exception {
ProcessBuilder pb = new ProcessBuilder();
pb.environment().put("DISPLAY", controller.getDisplay());
return pb.command("xclock").start();
}
});
Screenshot screenshot = controller.getScreenshooter().capture();
// do something with screenshot
processFuture.cancel(true);
}
Quickstart - JUnit Rule
-----------------------
### Maven
com.github.mike10004
xvfb-testing
0.4
### Code
@Rule
public XvfbRule xvfb = new XvfbRule();
@Test
public void testSomething() throws Exception {
XvfbController controller = xvfb.getController();
// use controller as in the core library example above
}
Modules
-------
The purpose of each module is as follows:
* **xvfb-manager**: core library
* **xvfb-testing**: JUnit Rule
* **xvfb-unittest-tools**: library only used by above projects for testing
* **xvfb-manager-example**: executable program demonstrating Selenium usage
Using with Selenium
-------------------
To use an `XvfbManager` instance with Selenium, start the virtual framebuffer
and then configure the webdriver process's environment with the appropriate
display. (There used to be an **xvfb-selenium** artifact that had a convenience
method for this, but I didn't like keeping up with the Selenium API changes.)
### Chrome
ChromeDriverService service = new ChromeDriverService.Builder()
.usingAnyFreePort()
.withEnvironment(ImmutableMap.of("DISPLAY", display))
.build();
return new ChromeDriver(service);
### Firefox
GeckoDriverService service = new GeckoDriverService.Builder()
.usingAnyFreePort()
.withEnvironment(ImmutableMap.of("DISPLAY", display))
.build();
FirefoxDriver driver = new FirefoxDriver(service);
Notes
-----
### Automatic Display Selection
Versions of Xvfb prior to 1.13 did not support the `-displayfd` option
that allows automatic selection of an open display number. If your
version of Xvfb is lower than 1.13, then you must specify a display
number. If using the core library, you would do that like this:
XvfbManager manager = new XvfbManager();
XvfbController controller = manager.start(99);
If using the JUnit rule, then the display number is specified like this:
public XvfbRule xvfb = XvfbRule.builder().onDisplay(99).build();
The display number `99` corresponds to the `DISPLAY` environment
variable value `:99`.
### Unit tests with Selenium
The unit tests that involve Selenium make use of [WebDriverManager]
to manage webdrivers for Chrome and Firefox. This library queries the
GitHub API and occasionally gets a 403 response due to [rate-limiting]
of anonymous requests. To make your requests non-anonymous and prevent
the rate-limiting from breaking the build:
1. Create a pair token/secret in your [GitHub account]
2. Set system properties `wdm.gitHubTokenName` and `wdm.gitHubTokenSecret`
for the build
Supported Operating Systems
---------------------------
Currently only Linux is supported, and the library has only been tested
on Ubuntu. In theory, it should work on Fedora-like platforms. Support
for MacOS has not been investigated. Support for Windows probably
wouldn't make sense.
Runtime and Unit Test Requirements
----------------------------------
Some programs are required to be installed at runtime, and many tests
will be skipped if certain programs are not available in the build
environment. These prerequisites are listed in the table below by
distribution.
Ubuntu 16.04
Fedora 24
Scope
xvfb
xorg-x11-server-Xvfb
runtime
netpbm
netpbm-progs
runtime
x11-utils
xorg-x11-utils
runtime
x11-apps
xorg-x11-apps
test
xdotool
xdotool
test
imagemagick
ImageMagick
test
firefox
firefox
test
google-chrome or chromium
google-chrome or chromium
test
FAQ
---
### Does it work on MacOS?
Not really, but you might be able to shoehorn it. You can install [XQuartz]
(see [Homebrew instructions]), but that version of Xvfb requires being
run as root (for the creation of secure directories in /tmp), and you should
be justifiably skeptical of anyone suggesting you run your unit tests as root.
You might be able to get around this be manually creating `/tmp/.X11-unix` as
root and setting its permissions to 1777 *before* you run your tests.
Acknowledgements
----------------
The photo used in the unit tests is by George Chernilevsky - Own work,
CC BY-SA 4.0, https://commons.wikimedia.org/w/index.php?curid=34785750.
[WebDriverManager]: https://github.com/bonigarcia/webdrivermanager
[rate-limiting]: https://developer.github.com/v3/#rate-limiting
[GitHub account]: https://github.com/settings/tokens
[Homebrew instructions]: http://macappstore.org/xquartz/