assertj-core-conditions.html

<!DOCTYPE html>
<html lang="en">

<head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <meta name="description" content="AssertJ site">
   <meta name="author" content="Joel Costigliola">

   <title>AssertJ / Fluent assertions for java</title>

   <!-- CSS -->
   <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Inconsolata|Source+Code+Pro|Open+Sans|Ubuntu|Varela+Round|Karla">
   <link href="css/bootstrap.min.css" rel="stylesheet">
   <link href="font-awesome/css/font-awesome.min.css" rel="stylesheet">
   <script src="highlight/highlight.pack.js"></script>
   <link rel="stylesheet" href="highlight/styles/railscasts.css">
   <script>hljs.initHighlightingOnLoad();</script>
   <link href="css/assertj.min.css" rel="stylesheet">
   <link rel="shortcut icon" href="favicon.png" />
</head>

<body>

<nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">
   <div class="container">
      <div class="navbar-header">
         <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-ex1-collapse">
            <span class="sr-only">Toggle navigation</span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
         </button>
         <!-- You'll want to use a responsive image option so this logo looks good on devices - I recommend using something like retina.js (do a quick Google search for it and you'll find it) -->
         <a class="navbar-brand" href="index.html">AssertJ</a>
      </div>

      <!-- Collect the nav links, forms, and other content for toggling -->
      <div class="collapse navbar-collapse navbar-ex1-collapse">
         <ul class="nav navbar-nav navbar-right">
            <li><a href="assertj-core-quick-start.html">Quick start</a></li>
            <li><a href="assertj-news.html">News</a></li>
            <li><a href="assertj-core.html">Core</a></li>
            <li><a href="assertj-assertions-generator.html">Assertions generator</a></li>
            <li><a href="assertj-guava.html">Guava</a></li>
            <li><a href="assertj-joda-time.html">Joda-Time</a></li>
            <li><a href="assertj-db.html">DB</a></li>
            <li><a href="assertj-neo4j.html">Neo4j</a></li>
            <li><a href="assertj-swing.html">Swing</a></li>
            <li><a href="assertj-help.html">Help</a></li>
         </ul>
      </div>
   </div>
</nav>


<div class="container">
   <div class="row">

            <div class="col-md-2 assertj-sidebar-menu">
         <div class="bs-sidebar hidden-print affix-top" role="complementary">
            <ul class="bs-sidenav nav ">
               <li class="sidenav-header">Main</li>
               <li><a href="assertj-core.html">Overview</a></li>
               <li><a href="assertj-core-quick-start.html">Quick start</a></li>
               <li><a href="assertj-core-news.html">News &amp; releases</a></li>
               <li><a href="assertj-core-features-highlight.html">Features highlight</a></li>
               <li><a href="assertj-core-conditions.html">Using conditions</a></li>
               <li><a href="assertj-core-custom-assertions.html">Custom assertions</a></li>
               <li><a href="http://joel-costigliola.github.io/assertj/core/api/index.html" target="_blank">Javadoc (2.x)</a></li>
               <li><a href="http://joel-costigliola.github.io/assertj/core-8/api/index.html" target="_blank">Javadoc (3.x)</a></li>
               <li><a href="assertj-core.html#help">Help &amp; F.A.Q</a></li>
               <li><a href="assertj-core.html#code">Code &amp; issues <i class="fa fa-github"></i></a></li>
               <li><a href="assertj-core.html#team">Team</a></li>
               <li><a href="assertj-core.html#contributing">Contributing</a></li>
               <li class="sidenav-header">Migrating</li>
               <li><a href="assertj-core-converting-junit-assertions-to-assertj.html">JUnit 4 Assertions</a></li>
               <li><a href="assertj-core-converting-junit5-assertions-to-assertj.html">JUnit 5 Assertions</a></li>
               <li><a href="assertj-core-converting-testng-assertions-to-assertj.html">TestNG Assertions</a></li>
               <li><a href="assertj-core-migrating-from-fest.html">Fest Assert</a></li>
            </ul>
         </div>
      </div>


      <div class="col-lg-10 col-md-10 col-sm-10 text-left">
         <h1 class="page-header">AssertJ Core new website!</h1>
         <h2 style="color:darkblue;font-style: italic;">AssertJ Core site has moved to <a href="https://assertj.github.io/doc/">https://assertj.github.io/doc/</a></h2>
      <h1 class="page-header">Extending assertions with conditions</h1>

         <p>Assertions provided by AssertJ can be extended by using conditions, to <a href="#creating-condition">create a condition</a>
            you just have to implement <span class="small-code">org.assertj.assertions.core.Condition</span> and its unique method <span class="small-code">matches</span>.</p>
         <p>Once your <span class="small-code">Condition</span> is created, you can use it with methods :
            <a href="#example-is"><span class="small-code">is(myCondition)</span></a> or <a href="#example-has"><span class="small-code">has(myCondition)</span></a>,
            both verifying that the condition is met (hint: pick the one that makes your code more readable).<br>
         Example:</p>

<pre><code class="java">// jedi is a Condition
assertThat("Yoda").is(jedi);</code></pre>

         <p>Conditions can be <a href="#example-combining-conditions">combined</a> with :</p>
         <ul>
            <li><span class="small-code">not(Condition)</span> : given condition must not be met</li>
            <li><span class="small-code">allOf(Condition...)</span> : all given conditions must be met</li>
            <li><span class="small-code">anyOf(Condition...)</span> : one of the given conditions must be met</li>
         </ul>

         <p>You can verify that a <span class="small-code">Condition</span> is met on <a href="#example-condition-on-collection">elements of a collection</a>, with the following methods:</p>
         <ul>
            <li><span class="small-code">are(condition)</span> / <span class="small-code">have(condition)</span> : all elements must meet the given condition</li>
            <li><span class="small-code">areAtLeast(n, condition)</span> / <span class="small-code">haveAtLeast(n, condition)</span> : at least <span class="small-code">n</span> elements must meet the given condition</li>
            <li><span class="small-code">areAtMost(n, condition)</span> / <span class="small-code">haveAtMost(n, condition)</span> : no more than <span class="small-code">n</span> elements must meet the given condition</li>
            <li><span class="small-code">areExactly(n, condition)</span> / <span class="small-code">haveExactly(n, condition)</span> : exactly <span class="small-code">n</span> elements must meet the given condition</li>
         </ul>

         <p>Moreover all Condition related methods have their negation counterpart, <span class="small-code">is/isNot</span>, <span class="small-code">have/doesNotHave</span>, <span class="small-code">are/areNot</span>, ...</p>

         <p>The examples below are from <a href="https://github.com/joel-costigliola/assertj-examples/">assertj-examples</a> and more specifically <a href="https://github.com/joel-costigliola/assertj-examples/blob/master/assertions-examples/src/test/java/org/assertj/examples/condition/UsingConditionExamples.java">UsingConditionExamples.java</a>.</p>

         <h3 class="page-header"><span id="creating-condition"></span>Creating condition</h3>
         <p>Let's define two similar conditions : <span class="small-code">jedi</span> and <span class="small-code">jediPower</span> with the same implementation just to show that code readability is better when using <span class="small-code">jedi</span> with <span class="small-code">is</span> and <span class="small-code">jediPower</span> with <span class="small-code">has</span>.</p>

<pre><code class="java">import static org.assertj.core.util.Sets.newLinkedHashSet;

static Set&lt;String&gt; JEDIS = newLinkedHashSet("Luke", "Yoda", "Obiwan");

// implementation with Java 8 :)
Condition&lt;String&gt; jediPower = new Condition&lt;&gt;(JEDIS::contains, "jedi power"); 

// implementation with Java 7 :(
Condition&lt;String&gt; jedi = new Condition&lt;String&gt;("jedi") {
  @Override
  public boolean matches(String value) {
    return JEDIS.contains(value);
  }
};
</code></pre>
         <h3 class="page-header"><span id="example-is"></span>Example using is / isNot </h3>
         <p>An small example of <span class="small-code">is(Condition)</span> and <span class="small-code">isNot(Condition)</span> usage including an error message.</p>
<pre><code class="java">assertThat("Yoda").is(jedi);
assertThat("Vader").isNot(jedi);
try {
  // condition not verified to show the clean error message
  assertThat("Vader").is(jedi);
} catch (AssertionError e) {
  assertThat(e).hasMessage("expecting:&lt;'Vader'&gt; to be:&lt;jedi&gt;");
}</code></pre>

               <h3 class="page-header"><span id="example-has"></span>Example using has/doesNotHave</h3>

         <p>An small example of <span class="small-code">has(Condition)</span> and <span class="small-code">doesNotHave(Condition)</span> usage including an error message.</p>
<pre><code class="java">assertThat("Yoda").has(jediPower);
assertThat("Solo").doesNotHave(jediPower);
try {
  // condition not verified to show the clean error message
  assertThat("Vader").has(jediPower);
} catch (AssertionError e) {
  assertThat(e).hasMessage("expecting:&lt;'Vader'&gt; to have:&lt;jedi power&gt;");
}</code></pre>

                     <h3 class="page-header"><span id="example-condition-on-collection"></span>Verifying condition on collection elements</h3>

         <p>It is possible to verify that a certain condition is met on iterable/array elements :</p>

<pre><code class="java">// import static org.assertj.util.Sets.newLinkedHashSet;
assertThat(newLinkedHashSet("Luke", "Yoda")).are(jedi);
assertThat(newLinkedHashSet("Leia", "Solo")).areNot(jedi);

assertThat(newLinkedHashSet("Luke", "Yoda")).have(jediPower);
assertThat(newLinkedHashSet("Leia", "Solo")).doNotHave(jediPower);

assertThat(newLinkedHashSet("Luke", "Yoda", "Leia")).areAtLeast(2, jedi);
assertThat(newLinkedHashSet("Luke", "Yoda", "Leia")).haveAtLeast(2, jediPower);

assertThat(newLinkedHashSet("Luke", "Yoda", "Leia")).areAtMost(2, jedi);
assertThat(newLinkedHashSet("Luke", "Yoda", "Leia")).haveAtMost(2, jediPower);

assertThat(newLinkedHashSet("Luke", "Yoda", "Leia")).areExactly(2, jedi);
assertThat(newLinkedHashSet("Luke", "Yoda", "Leia")).haveExactly(2, jediPower);</code></pre>

                     <h3 class="page-header"><span id="example-combining-conditions"></span>Combining conditions</h3>
         <p>Condition can be combined with <span class="small-code">allOf(Condition...)</span> (logical and) or <span class="small-code">anyOf(Condition...)</span> (logical or).</p>
<pre><code class="java">assertThat("Vader").is(anyOf(jedi, sith));
assertThat("Solo").is(allOf(not(jedi), not(sith)));</code></pre>

<p>where sith condition is defined as :</p>

<pre><code class="java">static Set&lt;String&gt; SITHS = newHashSet("Sidious", "Vader", "Plagueis");
Condition&lt;String&gt; sith = new Condition&lt;&gt;(SITHS::contains, "sith"); 
</code></pre>

      </div>
   </div>
</div>


<br>
<!--
<div class="container">
   <footer>
      <div class="row">
         <div class="col-lg-12">
            <p>AssertJ - Licensed under the Apache License, Version 2.0.</p>
         </div>
      </div>
   </footer>
</div>
-->

<script src="js/jquery-1.10.2.js"></script>
<script src="js/bootstrap.js"></script>
<script src="js/modern-business.js"></script>
<script src="js/assertj.js"></script>

</body>
</html>