clojure-test.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="clojure-test-compatibility" class="anchor" href="#clojure-test-compatibility"><span class="octicon octicon-link"></span></a>clojure.test compatibility</h2>
<p><code>clojure.test</code> compatibility is available via
  <a href="https://github.com/clojure-expectations/clojure-test">clojure-expectations/clojure-test</a>.</p>
  <p>Clojure CLI/<code>deps.edn</code>: <code>com.github.seancorfield/expectations {:mvn/version "RELEASE"}</code></p>
  <p>Leiningen/<code>project.clj</code>: <code>[com.github.seancorfield/expectations "RELEASE"]</code></p>
  <p>There is a new <code>expectations.clojure.test</code> namespace containing a <code>defexpect</code> macro that
  allows for named expectations to be defined, like <code>clojure.test</code>'s <code>deftest</code> macro.</p>
<div class="highlight"><pre>(ns example.test
  (:require [expectations.clojure.test :refer :all]))

;; a single named expectation
(defexpect two 2 (+ 1 1))

;; a named group of expectations
(defexpect group
  (expect [1 2] (conj [] 1 2))
  (expect #{1 2} (conj #{} 1 2))
  (expect {1 2} (assoc {} 1 2)))
</pre></div>
<p>Expectations defined this way can be run with regular <code>clojure.test</code>
  tooling, such as <code>lein test</code> or <code>boot test</code>,
  or via the "standard" test running commands within various Clojure-compatible
  editors that are designed to work with <code>clojure.test</code>.</p>
<p>All the regular <code>clojure.test</code> functionality should be in play
  at this point, including <code>use-fixtures</code> instead of Expectations'
  own in-context/before-run/after-run functionality.</p>
<p>The above code creates functions <code>two</code> and <code>group</code> that
  have <code>:test</code> metadata (containing the actual test expressions), and
  the functions themselves run <code>clojure.test/test-var</code> on themselves
  so you can call <code>(two)</code> and <code>(group)</code> to run those tests
  (and they will print out any failures), the same way <code>deftest</code> works.</p>

<p>You can intermix other code inside <code>defexpect</code>
  and you can nest <code>expect</code> forms inside other code.</p>

<p>You can wrap blocks of code in <code>expecting</code>
  to provide more descriptive test output -- mirroring <code>clojure.test/testing</code>:</p>
<div class="highlight"><pre>(ns example.test
  (:require [expectations.clojure.test :refer :all]))

;; a single named expectation
(defexpect two 2 (+ 1 1))

;; a named group of expectations
(defexpect group
  (expecting "conj should add each element"
    (expect [1 2] (conj [] 1 2))
    (expect #{1 2} (conj #{} 1 2)))
  (expect {1 2} (assoc {} 1 2)))
</pre></div>

<p>Note that <code>expectations.clojure.test</code> does not run tests on shutdown.
  Instead, tests are run on-demand via the usual <code>clojure.test</code> machinery and test runners.</p>

<h3>
  <a name="migrating-to-clojure-test" class="anchor" href="#migrating-to-clojure-test"><span class="octicon octicon-link"></span></a>migrating to clojure.test</h3>
<p>Given the streamlined simplicity of expectations, you might wonder why you
  would want to migrate your expectations test suite to <code>clojure.test</code>-style
  named tests? The short answer is <strong>tooling</strong>! Whilst we have
  well-maintained, stable plugins for Leiningen and Boot, as well as an Emacs mode,
  the reality is that Clojure tooling is constantly evolving and most of those
  tools -- such as the excellent <a href="https://cider.readthedocs.io/en/latest/">CIDER</a>,
  <a href="https://cursive-ide.com/">Cursive</a>,
  and the more recent <a href="https://atom.io/packages/proto-repl">ProtoREPL</a> (for Atom) --
  are going to focus on Clojure's built-in testing library first.
  Support for the original form of Expectations, using unnamed tests, is
  non-existent in Cursive, and can be problematic in other editors.
  A whole ecosystem
  of tooling has grown up around <code>clojure.test</code> and to take advantage of
  that with expectations, we either need to develop compatible extensions to each
  and every tool or we need expectations to be compatible with <code>clojure.test</code>.</p>
<p>One of the big obstacles for that compatibility is that, by default, expectations
  generates "random" function names for test code (the function names are based on the
  hashcode of the text form of the <code>expect</code> body), which means the test
  name changes whenever the text of the test changes. To address that, the new
  <code>expectations.clojure.test</code> namespace introduces named expectations via
  the <code>defexpect</code> macro (mimicking <code>clojure.test</code>'s <code>deftest</code>
  macro). Whilst this goes against the <a href="/odds-ends.html#oe">Test Names</a>
  philosophy that expectations was created with, it buys us a lot in terms of
  tooling support!</p>
<p>You can convert your test suite piecemeal, either replacing <code>expect</code>
  with <code>defexpect</code> (and a name) or wrapping several <code>expect</code>
  forms with a single <code>defexpect</code> (and a name). You can do this one
  namespace at a time, but you'll need to run both types of tests
  explicitly via tooling:</p>
<pre>
jfields$ lein do expectations, test

jfields$ boot expectations test
</pre>
<p>In addition to broader tooling support, you also get access to anything that
  is built on top of <code>clojure.test</code>, such as JUnit XML output,
  automatically.</p>
<p>What do you lose? Well, <code>clojure.test</code>-based failure reporting
  isn't as sophisticated as expectations-based failure reporting so you will
  lose some of the clarity and expressiveness there.</p>
      </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>