JConditions


Source link: https://github.com/vbauer/jconditions

JConditions

There is an exception to every rule.

JConditions is an extension for JUnit framework, which allows to mark test methods with specific conditional annotations. This annotations allow to permit or restrict execution of test methods. It helps to keep clean your test methods using declarative programming and prevents a lot of unnecessary code (see Assume class).

10 second example

A picture paints a thousand words:

@RunWith(ConditionTestRunner.class) public class ExampleTest {

  @Test
  @RunningOnOS(LINUX)
  public void testRunningOnOS() throws Exception {

// Check some Linux app

assertTrue(exec("some-linux-program"));

  
}

@Test
  @IfJavaVersion(JAVA_8)
  public void testIfJavaVersion8() {

// Check some Java 8 specific code

assertTrue(com.foo.Java8Class.isCorrect());

  
}

 
}

Features

JConditions has the following conditional annotations:

This annotations could be used with test methods or/and classes (it will allow to run checks before each test method). You can also write custom annotations or make composite annotations.

Setup

JConditions uses JitPack.io for distribution, so you need to configure JitPack's Maven repository to fetch artifacts (dependencies).

Maven

<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url> </repository>  <dependencies>
  <dependency>

<groupId>com.github.vbauer</groupId>

<artifactId>jconditions</artifactId>

<version>1.2.2</version>
  </dependency> </dependencies>

Gradle

repositories {

  mavenCentral()
  maven {

url 'https://jitpack.io'
  
}
 
}
  dependencies {

  testCompile 'com.github.vbauer:jconditions:1.2.2' 
}

Annotations

Some things that you need to know before exploring an examples:

  • Each described annotation has a simple example how to use it. Examples are very simple, they are existed only to show the main idea of usage.
  • Most of them could use injections to insert environment variables. This injections/substitutions could be useful to parametrize tests or to organize profiles. EX: "${ java.io.tmpdir } /test.html"

@AppIsInstalled

@AppIsInstalled checks that specified application(s) is installed. It could be useful when developed application has an optional integrations with some external tools/apps and it will be good to check this integrations in tests.

@Test @AppIsInstalled({
 "ls", "uname" 
}
) public void testAppIsInstalled() throws Exception {

  exec("ls");

  exec("uname");
 
}

@ExistsOnFS

@ExistsOnFS checks that specified file or directory is existed on file system. It is also possible to configure multiple values.

Available parameters:

  • value - file(s) or directory(ies).
  • type - type(s) of FS element (FILE / DIRECTORY / SYMLINK).
@Test @ExistsOnFS("pom.xml") public void testFileExists() throws Exception {

  Assert.assertTrue(FSUtils.fileExists("pom.xml"));
 
}

@HasClass

@HasClass checks that specified class(es) is available in classpath. It could be useful to check integration with optional features.

@Test @HasClass("org.junit.Assert") public void testHasClass() throws Exception {

  Assert.assertNotNull(Class.forName("org.junit.Assert"));
 
}

@HasFreeSpace

@HasFreeSpace checks that FS element(s) / disk(s) has free space. It could be useful to check if it is possible to:

  • download some big some file from remote server
  • generate and store on FS some data

Available parameters:

  • value - disk or disks that should be checked (ex: "C:\").
  • min - minimum amount of available free space on disk in bytes.
  • max - maximum amount of available free space on disk in bytes.
@Test @HasFreeSpace(value = {
 "/", "C:\\" 
}
, min = 1024) public void testHasFreeSpace() {

  // Download some file 
}

@HasPackage

@HasPackage checks that specified package(s) is available in classpath. It could be useful to check integration with optional features.

@Test @HasPackage("org.junit") public void testHasPackage() throws Exception {

  Assert.assertNotNull(Package.getPackage("org.junit"));
 
}

@IfJavaVersion

@IfJavaVersion checks that test is run on the specific version(s) of JVM.

EX: Some features could use external libraries and work only for the specific version of JVM. It is possible to check it, if you use full names for classes (class loader will load them in runtime).

@Test @IfJavaVersion(IfJavaVersion.JAVA_8) public void testIfJavaVersion8() {

  Assert.assertTrue(IfJavaVersionChecker.javaVersion().contains("8"));

  // Javaslang project works only on Java 8
  Assert.assertNotNull(javaslang.Tuple0.instance());
 
}

@IfScript

@IfScript allows to write custom conditional rules using JSR 223: Scripting for the JavaTM Platform. JavaScript engine is available by default (it is part of JVM). All other JSR233-compatible languages will be included automatically if they are available in classpath.

Available parameters:

  • values - script or scripts that should be executed. Return value will be converted to boolean type (even String and Numbers).
  • engine - type of script engine (default value is "js").
  • context - context provider which provides an extra data in script as "context" variable.

Parameters which are available in script context:

  • test - current instance of running test class.
  • env - environment variables ( System.getenv()).
  • props - system properties ( System.getProperties()).
  • console - console object ( System.console()).
  • context - extra data which could be created using context provider.
@Test @IfScript("test.isSatisfiedInnerCheck") public void testIfScriptNegative() {

  Assert.fail();
 
}

@IgnoreIf

@IgnoreIf allows to skip some test method using specific ConditionChecker class. It will skip test, if checker return true and execute method otherwise. ConditionChecker could be separate class, or nested static class, or even inner class. It also works fine with private classes.

@Test @IgnoreIf(Always.class) public void testIgnoreIfAlways() {

  Assert.fail();
 
}

@PropertyIsDefined

@PropertyIsDefined checks if environment or system property is defined. It could be useful to simulate test profiles or to check some cases which are dependent on them (and could be optionals).

Available parameters:

  • keys - keys of environment or system variables
  • values - values that should correspond to keys (optional parameter).
@Test @PropertyIsDefined(keys = "os.name") public void testEnvVarIsDefined() {

  Assert.assertNotNull(PropUtils.getSystemProperty("os.name"));
 
}

@ResourceIsAvailable

@ResourceIsAvailable allows to minimize code which is necessary to download some document/file via HTTP/HTTPS. It is also possible to cache downloaded resource between test executions, otherwise it will be remove after test.

Available parameters:

  • source - HTTP/HTTPS file or document.
  • target - path to file where content should be saved.
  • cache - flag to configure cache option.
  • timeout - maximum time for connection to the source (default value is 10sec).
@Test @ResourceIsAvailable(
  source = "http://apple.com",
  target = "${
java.io.tmpdir
}
/apple-homepage.html",
  cache = false ) public void testResourceIsAvailable() {

  final String path = PropUtils.injectProperties("${
java.io.tmpdir
}
/apple-homepage.html");

  Assert.assertTrue(FSUtils.fileExists(path));
 
}

@RunIf

@RunIf is an opposite annotation to @IgnoreIf. It will run test method if ConditionChecker returns true.

@Test @RunIf(SomeInnerClassCheck.class) public void testInnerClass() {

  Assert.fail();
 
}

@RunningOnOS

@RunningOnOS checks the current operation system and runs test method only when it is specified and value parameter. It is also possible to configure multiple variants (to run test method, even one of them should be fine).

@Test @RunningOnOS({

  RunningOnOS.LINUX,
  RunningOnOS.MAC, 
}
) public void testRunningOnOS() throws Exception {

  Assert.assertTrue(exec("ls"));
 
}

@SocketIsOpened

@SocketIsOpened checks that specified socket is opened.

Available parameters:

  • host - host address (default value is "0.0.0.0").
  • port - socket's port number.
  • timeout - maximum time for connection to the socket (default value is 10sec).
@Test @SocketIsOpened(host = "apple.com", port = 80) public void testSocketIsOpened() throws Exception {

  checkSite("http://apple.com");
 
}

@UrlIsReachable

@UrlIsReachable checks that specified URL address is reachable (available via URLConnection). It also possible to configure multiple URLs.

Available parameters:

  • value - URL address(s) that should be checked.
  • timeout - maximum timeout for URL connection (default value is 10sec).
@Test @UrlIsReachable("http://apple.com") public void testUrlIsReachable() throws Exception {

  checkSite("http://apple.com");
 
}

Custom annotations

It is possible use @IfRun or @IgnoreIf to run custom ConditionalChecker, but it is also possible to write your own annotation (like @HasPackage or @IfScript).

All JConditions out-of-box annotations was created using unified extension mechanism. This mechanism is centered around 3 main things:

  • Custom annotation which can has additional parameters that could be used as input data.
  • Conditional checker which make decision to permit or restrict running of test method.
  • @Condition annotation which allows to glue custom annotation and conditional checker.

Let's write an annotation which emulates standard JUnit's @org.junit.Ignore:

@Condition(IgnoreItChecker.class) @Retention(RetentionPolicy.RUNTIME) @Target({
 ElementType.ANNOTATION_TYPE, ElementType.TYPE, ElementType.METHOD 
}
) public @interface IgnoreIt {
 
}
  public class IgnoreItChecker implements ConditionChecker<IgnoreIt> {

  @Override
  public boolean isSatisfied(final CheckerContext<IgnoreIt> context) {

return false;
  
}
  
}

That's all! Now, you can mark test classes or test methods with @IgnoreIt to skip test(s).

Composite annotations

Sometimes it could be useful to have possibility to resolve the following cases (to prevent unnecessary code):

  • Specify all needed parameter for some existed annotation and do not copy-paste them.
  • Glue some conditional annotations into one annotation.

It is possible, because JConditions extension mechanism resolves all hierarchy of classes and annotations.

Let's make an annotation which allows to detect if our MySQL database works fine:

@SocketIsOpened(host = "localhost", port = 3306) @Retention(RetentionPolicy.RUNTIME) @Target({
 ElementType.ANNOTATION_TYPE, ElementType.METHOD 
}
) public @interface MySQLWorks {
 
}

Let's make an annotation which allows to run tests only on Linux machines with Java 8:

@RunningOnOS(LINUX) @IfJavaVersion(JAVA_8) @Retention(RetentionPolicy.RUNTIME) @Target({
 ElementType.ANNOTATION_TYPE, ElementType.METHOD 
}
) public @interface OnLinuxWithJava8 {
 
}

Building from source

JConditions uses Maven for its build. To build project, run:

mvn clean install -P strict

from the root of the project directory. Profile strict is necessary to check code style and to run static code analysis.

Might also like

  • jackdaw - Java Annotation Processor which allows to simplify development.
  • caesar - Library that allows to create async beans from sync beans.
  • houdini - Type conversion system for Spring framework.
  • herald - Logging annotation for Spring framework.
  • commons-vfs2-cifs - SMB/CIFS provider for Commons VFS.
  • avconv4java - Java interface to avconv tool.

License

Copyright 2015 Vladislav Bauer

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0 

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See LICENSE file for details.

Resources

A custom ImageView that provides dragging and scaling.

Preferences Editor makes it easy to add, edit, remove keys from shared preferences files.

It defines a BroadcastReceiver that will make changes to your shared preferences based on received actions and data.

Simple android view to display gifs efficiently. You can start, pause and stop gifView.

Global Utilities for Android.

A Tinder style Swipe-able deck view for Android.

This repository demonstrates the Model View Presenter architecture.

Topics


2D Engines   3D Engines   9-Patch   Action Bars   Activities   ADB   Advertisements   Analytics   Animations   ANR   AOP   API   APK   APT   Architecture   Audio   Autocomplete   Background Processing   Backward Compatibility   Badges   Bar Codes   Benchmarking   Bitmaps   Bluetooth   Blur Effects   Bread Crumbs   BRMS   Browser Extensions   Build Systems   Bundles   Buttons   Caching   Camera   Canvas   Cards   Carousels   Changelog   Checkboxes   Cloud Storages   Color Analysis   Color Pickers   Colors   Comet/Push   Compass Sensors   Conferences   Content Providers   Continuous Integration   Crash Reports   Credit Cards   Credits   CSV   Curl/Flip   Data Binding   Data Generators   Data Structures   Database   Database Browsers   Date &   Debugging   Decompilers   Deep Links   Dependency Injections   Design   Design Patterns   Dex   Dialogs   Distributed Computing   Distribution Platforms   Download Managers   Drawables   Emoji   Emulators   EPUB   Equalizers &   Event Buses   Exception Handling   Face Recognition   Feedback &   File System   File/Directory   Fingerprint   Floating Action   Fonts   Forms   Fragments   FRP   FSM   Functional Programming   Gamepads   Games   Geocaching   Gestures   GIF   Glow Pad   Gradle Plugins   Graphics   Grid Views   Highlighting   HTML   HTTP Mocking   Icons   IDE   IDE Plugins   Image Croppers   Image Loaders   Image Pickers   Image Processing   Image Views   Instrumentation   Intents   Job Schedulers   JSON   Keyboard   Kotlin   Layouts   Library Demos   List View   List Views   Localization   Location   Lock Patterns   Logcat   Logging   Mails   Maps   Markdown   Mathematics   Maven Plugins   MBaaS   Media   Menus   Messaging   MIME   Mobile Web   Native Image   Navigation   NDK   Networking   NFC   NoSQL   Number Pickers   OAuth   Object Mocking   OCR Engines   OpenGL   ORM   Other Pickers   Parallax List   Parcelables   Particle Systems   Password Inputs   PDF   Permissions   Physics Engines   Platforms   Plugin Frameworks   Preferences   Progress Indicators   ProGuard   Properties   Protocol Buffer   Pull To   Purchases   Push/Pull   QR Codes   Quick Return   Radio Buttons   Range Bars   Ratings   Recycler Views   Resources   REST   Ripple Effects   RSS   Screenshots   Scripting   Scroll Views   SDK   Search Inputs   Security   Sensors   Services   Showcase Views   Signatures   Sliding Panels   Snackbars   SOAP   Social Networks   Spannable   Spinners   Splash Screens   SSH   Static Analysis   Status Bars   Styling   SVG   System   Tags   Task Managers   TDD &   Template Engines   Testing   Testing Tools   Text Formatting   Text Views   Text Watchers   Text-to   Toasts   Toolkits For   Tools   Tooltips   Trainings   TV   Twitter   Updaters   USB   User Stories   Utils   Validation   Video   View Adapters   View Pagers   Views   Watch Face   Wearable Data   Wearables   Weather   Web Tools   Web Views   WebRTC   WebSockets   Wheel Widgets   Wi-Fi   Widgets   Windows   Wizards   XML   XMPP   YAML   ZIP Codes