odds-ends.html

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="chrome=1">
    <title>Expectations by jaycfields</title>

    <link rel="stylesheet" href="stylesheets/styles.css">
    <link rel="stylesheet" href="stylesheets/pygment_trac.css">
    <script src="javascripts/scale.fix.js"></script>
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
    <!--[if lt IE 9]>
    <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
  </head>
  <body>
    <div class="wrapper">
      <header>
        <h1 class="header">Expectations</h1>
        <p class="header">a minimalist's unit testing framework</p>

        <ul>
          <li><a class="buttons" href="index.html">Home</a></li>
          <li><a class="buttons" href="installing.html">Installing</a></li>
          <li><a class="buttons" href="introduction.html">Introduction</a></li>
          <li><a class="buttons" href="advanced.html">Advanced</a></li>
          <li><a class="buttons" href="collections.html">Collections</a></li>
          <li><a class="buttons" href="templating.html">Expect More</a></li>
          <li><a class="buttons" href="odds-ends.html">Odds & Ends</a></li>
          <li><a class="buttons" href="in-context.html">Around Each</a></li>
          <li><a class="buttons" href="before-run-hook.html">Around Suite</a></li>
          <li><a class="buttons" href="state-warnings.html">State Warnings</a></li>
          <li><a class="buttons" href="redef-state.html">Redef State</a></li>
          <li><a class="buttons" href="interactions.html">Side Effects</a></li>
          <li><a class="buttons" href="freeze-time.html">Freeze Time</a></li>
          <li><a class="buttons" href="env-tweaks.html">ENV Tweaks</a></li>
          <li><a class="buttons" href="emacs-tweaks.html">emacs Tweaks</a></li>
<li><a class="buttons" href="clojure-test.html">clojure.test</a></li>
          <li><a class="buttons github" href="https://github.com/clojure-expectations/expectations">View On GitHub</a></li>
        </ul>

        <p class="header">This project is maintained by <a class="header name" href="https://github.com/seancorfield">seancorfield</a> and <a class="header name" href="https://github.com/jaycfields">jaycfields</a></p>


      </header>
      <section>
        <h1>
<a name="expectations" class="anchor" href="#expectations"><span class="octicon octicon-link"></span></a>expectations</h1>

<blockquote>
<p>adding signal, removing noise</p>
</blockquote>

<h2>
<a name="oe" class="anchor" href="#oe"><span class="octicon octicon-link"></span></a>Stacktraces, Test Names, Focused Tests, & JUnit Integration</h2>

The previous sections on <a href="https://github.com/clojure-expectations/expectations">expectations</a> unit testing syntax cover all of the various ways that expectations can be used to write tests
and what you can expect when your tests fail. However, there are a few other things worth knowing about expectations.<br />
<br />
<span style="font-weight: bold;">Stacktraces</span><br />
expectations aggressively removes lines from the stacktraces. Just like many other aspects of expectations, the focus is on more signal and less noise.
Any line in the stacktrace from clojure.core, clojure.lang, clojure.main, and java.lang will be removed. As a result any line appearing in your stacktrace should be
relevant to your application or a third-party lib you're using. expectations also removes any duplicates that can occasionally appear when anonymous functions are part of the stacktrace.
Again, it's all about improving signal by removing noise. Speaking of noise...<br />
<br />
<span style="font-weight: bold;">Test Names</span><br />
You might have noticed that expectations does not require you to create a test name.
This is a reflection of my personal opinion that <a href="http://blog.jayfields.com/2008/05/testing-value-of-test-names.html">test names are nothing more than comments</a> and shouldn't be required.
If you desire test names, feel free to drop a comment above each test. Truthfully, this is probably a better solution anyway, since you can use spaces (instead of dashes) to separate words in a comment.
Comments are good when used properly, but they can become noise when they are required. The decision to simply use comments for test names is another example of improving signal by removing noise.<br />
<br />
<span style="font-weight: bold;">Running Focused Expectations</span><br />
Sometimes you'll have a file full of expectations, but you only want to run a specific expectation - expectations solves this problem by giving you 'expect-focused'.
If you use expect-focused only expectations that are defined using expect-focused will be run.<br />
<br />
For example, if you have the following expectations in a file you should see the following results from 'lein expectations'.<br />
<pre>(ns sample.test.core
  (:require [expectations :refer :all]))

(expect zero? 0)
(expect zero? 1)
(expect-focused nil? nil)

jfields$ lein expectations
Ran 1 tests containing 1 assertions in 2 msecs
IGNORED 2 EXPECTATIONS
0 failures, 0 errors.</pre>
As you can see, expectations only ran one test - the expect-focused on line 6. If the other tests had been run the test on line 5 would have created a failure. It can be easy to accidentally leave a few expect-focused calls in, so expectations prints the number of ignored expectations in capital letters as a reminder. Focused expectation running is yet another way to remove noise while working through a problem.<br />
Note that focused expectations are only available with Expectations-specific tooling, using the original, unnamed test approach.
<br />
<span style="font-weight: bold;">Test Running</span><br />
If you always use 'lein expectations' to run your tests you'll never even care; however, if you ever want to run individual test files it's important to know that your tests run by default on JVM shutdown. When I'm working with Clojure and Java I usually end up using IntelliJ, and therefore have the ability to easily run individual files. When I switched from clojure.test to expectations I wanted to make test running as simple as possible - so I removed the need to specify (run-all-tests). Of course, if you don't want expectations to run for some reason you can disable this feature by calling (expectations/disable-run-on-shutdown).<br />
<br />
<span style="font-weight: bold;">JUnit Integration</span><br />
Lack of JUnit integration was a deal breaker for my team in the early days, so expectations comes with an easy way to run all tests as part of JUnit. If you want all of your tests to run in JUnit all you need to do is implement ExpectationsTestRunner.TestSource. The following example is what I use to run all the tests in expectations with JUnit.<br />
<pre>import expectations.junit.ExpectationsTestRunner;
import org.junit.runner.RunWith;

@RunWith(expectations.junit.ExpectationsTestRunner.class)
public class SuccessTest implements ExpectationsTestRunner.TestSource{

    public String testPath() {
        return "test/clojure/success";
    }
}</pre>
As you can see from the example above, all you need to do is tell the test runner where to find your Clojure files.
      </section>
      <footer>
        <p><small>Hosted on <a href="https://pages.github.com">GitHub Pages</a> using the Dinky theme</small></p>
      </footer>
    </div>
    <!--[if !IE]><script>fixScale(document);</script><![endif]-->

  </body>
</html>