<dependency>
<groupId>org.twinnation</groupId>
<artifactId>super-assert</artifactId>
<version>1.0.2</version>
</dependency>
Heavily inspired by Spring Framework's
Assert
class in org.springframework.util
and JUnit's assertion library, SuperAssert's goal is to provide a complete
one-line assertion solution with custom exception support. This library is not meant to be used for testing.
By providing a one-line solution, developers significantly enhance the readability of their code by reducing the amount of lines taken by minor, but sometimes numerous checks like this:
if (username == null || username.length == 0) {
throw new Exception("...");
}
and instead, use an elegant one-line solution like this:
SuperAssert.isTrue(username == null || username.length == 0, "...");
In fact, SuperAssert shines even more when you want to give more details to each specific error cases:
SuperAssert.notNull(username, "Your username cannot be null");
SuperAssert.isFalse(username.isEmpty(), "Your username cannot be blank");
SuperAssert.isAlphanumeric(username, "Your username must contain only alphanumeric characters");
SuperAssert.isNull(getUserByUsername(username), "The username you selected is already taken by another user");
SuperAssert.isAscii(password, "Your password cannot use illegal characters");
As this project is currently in progress, you're welcome to contribute.
By default, SuperAssert will throw an IllegalArgumentException
with the message passed as parameter.
It's very important to understand that IllegalArgumentException
is an unchecked exception, meaning that
using SuperAssert does not require you to declare an exception in the method's or in the constructor's throws
clause
unless you specify a custom checked exception.
- The name of the method is what is expected.
- The first parameter is what is being asserted.
- The last parameter is what will be thrown if the assertion fails.
e.g. SuperAssert.isTrue(condition, messageOrException);
The above would translate to:
I'm expecting that
condition
isTrue
and if it is not, thenmessageOrException
will be thrown.
SuperAssert.notNull(object, "The object passed as parameter cannot be null");
Using custom exceptions involves passing the exception message as parameter to your custom exception and then passing that custom exception as parameter instead of the message in the SuperAssert method.
SuperAssert.notNull(object, new CustomException("The object passed as parameter cannot be null"));
Going from using the default exception chosen by SuperAssert to a custom exception:
SuperAssert.notNull(user, "User cannot be null");
translates to
SuperAssert.notNull(user, new CustomException("User cannot be null"));
public User getUserById(Long id) {
SuperAssert.notNull(id, "A user cannot have a null id.");
return userRepository.findById(id).orElse(null);
}
public User createUser(String username, String password) {
SuperAssert.notNull(username, "Username cannot be null");
SuperAssert.notNull(password, "Password cannot be null");
SuperAssert.isAlphanumeric(username, "Username can only contain the following: a-z A-Z 0-9");
SuperAssert.isAscii(password, "Password contains invalid character");
SuperAssert.isNull(getUserByUsername(username), "Username is already taken");
return userRepository.save(new User(username, hash(password)));
}
Syntax: SuperAssert.notNull(object, message | exception)
Asserts whether an object is not null.
- If it is null, an exception will be thrown
- If it isn't null,
true
will be returned
This will throw an exception, because the assertion that the user
is notNull
is wrong (the user is null):
User user = null;
SuperAssert.notNull(user, "User cannot be null");
This will return true
, because the assertion that the user
is notNull
is correct (the user is not null):
User user = new User();
SuperAssert.notNull(user, "User cannot be null");
Syntax: SuperAssert.isNull(object, message | exception)
Asserts whether an object is null.
- If it is not null, an exception will be thrown
- If it is null,
true
will be returned
This will throw an exception, because the assertion that the user
isNull
is wrong (the user is not null):
User user = new User();
SuperAssert.notNull(user, "User already exists");
This will return true
, because the assertion that the user
isNull
is correct (the user is null):
User user = null;
SuperAssert.notNull(user, "User already exists");
Syntax: SuperAssert.isTrue(object, message | exception)
Asserts whether a boolean is true.
- If it is
true
,true
will be returned - If it is
false
, an exception will be thrown
This will throw an exception, because the assertion that the title.isEmpty()
condition isTrue
is wrong (the title is not empty):
String title = "Some pretty cool title";
SuperAssert.isTrue(title.isEmpty(), "Title cannot be empty");
This will return true
, because the assertion that the title.isEmpty()
condition isTrue
is correct (the title is empty):
String title = "";
SuperAssert.isTrue(title.isEmpty(), "Title cannot be empty");
Syntax: SuperAssert.isFalse(object, message | exception)
Asserts whether a boolean is false.
- If it is
true
, an exception will be thrown - If it is
false
,true
will be returned
This will throw an exception, because the assertion that the locked
condition isFalse
is wrong:
boolean locked = true;
SuperAssert.isFalse(closed, "The door is locked, you can't get in!");
This will return true
, because the assertion that the locked
condition isFalse
is correct:
boolean locked = false;
SuperAssert.isFalse(closed, "The door is locked, you can't get in!");
Syntax: SuperAssert.notEmpty(object, message | exception)
Asserts whether a list is not empty.
- If it is empty, an exception will be thrown
- If it is not empty,
true
will be returned
This will throw an exception, because the assertion that the list of users
is notEmpty
is wrong:
List<User> users = new ArrayList<>();
SuperAssert.notEmpty(users, "The user list cannot be empty!");
This will return true
, because the assertion that the list of users
is notEmpty
is correct:
List<User> users = Arrays.asList(user1, user2, ...);
SuperAssert.notEmpty(users, "The user list cannot be empty!");
Syntax: SuperAssert.notEmptyOrNull(object, message | exception)
Asserts whether a list is not empty or null.
- If it is empty or null, an exception will be thrown
- If it is not empty or null,
true
will be returned
In essence, this method is just an aggregation of notNull
and notEmpty
.
This will throw an exception, because the assertion that the list of users
is notEmptyOrNull
is wrong (the user list is null):
List<User> users = null;
SuperAssert.notEmptyOrNull(users, "The user list cannot be empty or null!");
This will return true
, because the assertion that the list of users
is notEmptyOrNull
is correct:
List<User> users = Arrays.asList(user1, user2, ...);
SuperAssert.notEmptyOrNull(users, "The user list cannot be empty or null!");
Syntax: SuperAssert.isAscii(string | char, message | exception)
Asserts whether a character/string is a printable ASCII.
- If it is not a printable ASCII character, an exception will be thrown
- If it is,
true
will be returned
NOTE: While the name of this method is isAscii
, be aware that this assumes PRINTABLE
ASCII characters. In other words, characters whose value is between 32 and 126 inclusively.
This will throw an exception, because the assertion that the string message
isAscii
is wrong:
String message = "Well,\n this is pretty cool!";
SuperAssert.isAscii(message, "Invalid characters");
This will return true
, because the assertion that the string message
isAscii
is correct:
String message = "Well, This is pretty cool!";
SuperAssert.isAscii(message, "Invalid characters");
Syntax: SuperAssert.isAlphanumeric(string | char, message | exception)
Asserts whether a character/string is alphanumeric.
- If it is not alphanumeric, an exception will be thrown
- If it is,
true
will be returned
This will throw an exception, because the assertion that the string username
isAlphanumeric
is wrong:
String username = "John Doe";
SuperAssert.isAlphanumeric(username, "Username must be alphanumeric (a-z A-Z 0-9)");
This will return true
, because the assertion that the string username
isAlphanumeric
is correct:
String username = "J0hnD03";
SuperAssert.isAlphanumeric(username, "Username must be alphanumeric (a-z A-Z 0-9)");
Syntax: SuperAssert.hasLength(string, minLength, [maxLength], message | exception)
Asserts whether a string respects the minimum and, if application, maximum length.
- If it the length constraints are not respected, an exception will be thrown
- If they are respected,
true
will be returned
The maxLength
parameter is optional. If you do decide to use a maximum length, keep in mind that it
has to be higher than the minLength
. Failure to do so will result in an AssertionError
.
This will throw an exception, because the assertion that the string password
hasLength
with minLength=8
and maxLength=32
is wrong:
String password = "secret";
SuperAssert.hasLength(password, 8, 32, "Your password must be between 8 and 32 characters inclusively");
This will return true
, because the assertion that the string password
hasLength
with minLength=8
and maxLength=32
is correct:
String password = "password123";
SuperAssert.hasLength(password, 8, 32, "Your password must be between 8 and 32 characters inclusively");
- Return nothing instead of
true
.- Update tests, documentation and comments accordingly