docs/blog/2012/06/constant-stubbing-in-rspec-2-11/index.html

<!DOCTYPE html>
<!--[if lt IE 7]><html class="no-js lt-ie9 lt-ie8 lt-ie7" lang="en"><![endif]-->
<!--[if IE 7]><html class="no-js lt-ie9 lt-ie8" lang="en"><![endif]-->
<!--[if IE 8]><html class="no-js lt-ie9" lang="en"><![endif]-->
<!--[if gt IE 8]<!--><html class="no-js" lang="en"><!--<![endif]--><head><meta charset="UTF-8" /><meta content="width=device-width, initial-scale=1" name="viewport" /><meta content="Constant Stubbing in RSpec 2.11" property="og:title" /><meta content="https://rspec.info/blog/2012/06/constant-stubbing-in-rspec-2-11/" property="og:url" /><meta content="https://rspec.info/images/logo_ogp.png" property="og:image" /><meta content="summary" name="twitter:card" /><meta content="@rspec" name="twitter:site" /><title>Constant Stubbing in RSpec 2.11</title><link href="/stylesheets/pages/blog.css" rel="stylesheet" type="text/css" /><link href="https://fonts.googleapis.com/css?family=Montserrat:400,700" rel="stylesheet" type="text/css" /><link href="https://fonts.googleapis.com/css?family=Source+Sans+Pro" rel="stylesheet" type="text/css" /><link href="https://fonts.googleapis.com/css?family=Inconsolata" rel="stylesheet" type="text/css" /><link href="/blog/feed.xml" rel="alternate" type="application/atom+xml" /></head><body class="blog"><header><nav><h1><img alt="Logo" src="/images/logo.png" /><a href="/">RSpec</a></h1><input class="hamburger-toggle" type="checkbox" /><div class="hamburger-icon"><div class="bar"></div><div class="bar"></div><div class="bar"></div></div><ul class="menu"><li><a href="/about">About</a></li><li><a href="/documentation">Documentation</a></li><li><a href="/blog">Blog</a></li><li><a href="/upgrading-from-rspec-2">Upgrade</a></li><li><a href="/help">Get Help</a></li><li><a href="/contributing">Contributing</a></li></ul></nav></header><section><article class="blog_post"><h1>Constant Stubbing in RSpec 2.11</h1><h3 class="author">Myron Marston</h3><small class="date">Jun 29, 2012</small><p>In the 2.11 release, rspec-mocks is gaining a significant new
capability that, as far as I know, isn't provided by any other
ruby mocking library: constant stubbing<sup id="fnref:foot_1"><a href="#fn:foot_1" class="footnote">1</a></sup>.</p>

<p>Let's look at the API, and then talk a bit about some of
the use cases for it.</p>

<h2 id="the-api">The API</h2>

<p>The main API is <code>stub_const</code>:</p>

<div class="highlight"><pre class="highlight ruby"><code><span class="n">describe</span> <span class="s2">"stub_const"</span> <span class="k">do</span>
  <span class="n">it</span> <span class="s2">"changes the constant value for the duration of the example"</span> <span class="k">do</span>
    <span class="n">stub_const</span><span class="p">(</span><span class="s2">"Foo::SIZE"</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
    <span class="n">expect</span><span class="p">(</span><span class="no">Foo</span><span class="o">::</span><span class="no">SIZE</span><span class="p">).</span><span class="nf">to</span> <span class="n">eq</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div>
<p>This works for both defined and undefined constants; you
could stub <code>A::B::C::D::E::F</code> even if none of the intermediary
constants exist. When the example completes, the constants will
be restored to their original states: any newly defined constants
will be undefined, and any modified constants will be restored
to their original values.</p>

<p>Note that constant names must be fully qualified; the current
module nesting is not considered:</p>

<div class="highlight"><pre class="highlight ruby"><code><span class="k">module</span> <span class="nn">MyGem</span>
  <span class="k">class</span> <span class="nc">SomeClass</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>

<span class="k">module</span> <span class="nn">MyGem</span>
  <span class="n">describe</span> <span class="s2">"Something"</span> <span class="k">do</span>
    <span class="n">let</span><span class="p">(</span><span class="ss">:fake_class</span><span class="p">)</span> <span class="p">{</span> <span class="no">Class</span><span class="p">.</span><span class="nf">new</span> <span class="p">}</span>

    <span class="n">it</span> <span class="s2">"accidentally stubs the wrong constant"</span> <span class="k">do</span>
      <span class="c1"># this stubs ::SomeClass (in the top-level namespace),</span>
      <span class="c1"># not MyGem::SomeClass like you probably mean.</span>
      <span class="n">stub_const</span><span class="p">(</span><span class="s2">"SomeClass"</span><span class="p">,</span> <span class="n">fake_class</span><span class="p">)</span>
    <span class="k">end</span>

    <span class="n">it</span> <span class="s2">"stubs the right constant"</span> <span class="k">do</span>
      <span class="n">stub_const</span><span class="p">(</span><span class="s2">"MyGem::SomeClass"</span><span class="p">,</span> <span class="n">fake_class</span><span class="p">)</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div>
<p><code>stub_const</code> also supports a <code>:transfer_nested_constants</code> option.
Consider a case where you have nested constants:</p>

<div class="highlight"><pre class="highlight ruby"><code><span class="k">class</span> <span class="nc">CardDeck</span>
  <span class="no">SUITS</span> <span class="o">=</span> <span class="p">[</span><span class="ss">:spades</span><span class="p">,</span> <span class="ss">:diamonds</span><span class="p">,</span> <span class="ss">:clubs</span><span class="p">,</span> <span class="ss">:hearts</span><span class="p">]</span>
  <span class="no">NUM_CARDS</span> <span class="o">=</span> <span class="mi">52</span>
<span class="k">end</span>
</code></pre></div>
<p><code>stub_const("CardDeck", fake_class)</code> cuts off access to the
nested constants (<code>CardDeck::SUITS</code> and <code>CardDeck::NUM_CARDS</code>),
unless you manually assign <code>fake_class::SUITS</code> and
<code>fake_class::NUM_CARDS</code>. The <code>:transfer_nested_constants</code>
option is provided to take care of this for you:</p>

<div class="highlight"><pre class="highlight ruby"><code><span class="c1"># Default behavior:</span>
<span class="n">fake_class</span> <span class="o">=</span> <span class="no">Class</span><span class="p">.</span><span class="nf">new</span>
<span class="n">stub_const</span><span class="p">(</span><span class="s2">"CardDeck"</span><span class="p">,</span> <span class="n">fake_class</span><span class="p">)</span>
<span class="no">CardDeck</span> <span class="c1"># =&gt; fake_class</span>
<span class="no">CardDeck</span><span class="o">::</span><span class="no">SUITS</span> <span class="c1"># =&gt; raises uninitialized constant error</span>
<span class="no">CardDeck</span><span class="o">::</span><span class="no">NUM_CARDS</span> <span class="c1"># =&gt; raises uninitialized constant error</span>

<span class="c1"># `:transfer_nested_constants =&gt; true` transfers all nested constants:</span>
<span class="n">stub_const</span><span class="p">(</span><span class="s2">"CardDeck"</span><span class="p">,</span> <span class="n">fake_class</span><span class="p">,</span> <span class="ss">:transfer_nested_constants</span> <span class="o">=&gt;</span> <span class="kp">true</span><span class="p">)</span>
<span class="no">CardDeck</span><span class="o">::</span><span class="no">SUITS</span> <span class="c1"># =&gt; [:spades, :diamonds, :clubs, :hearts]</span>
<span class="no">CardDeck</span><span class="o">::</span><span class="no">NUM_CARDS</span> <span class="c1"># =&gt; 52</span>

<span class="c1"># Or you can specify a list of constants to transfer:</span>
<span class="n">stub_const</span><span class="p">(</span><span class="s2">"CardDeck"</span><span class="p">,</span> <span class="n">fake_class</span><span class="p">,</span> <span class="ss">:transfer_nested_constants</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="ss">:SUITS</span><span class="p">])</span>
<span class="no">CardDeck</span><span class="o">::</span><span class="no">SUITS</span> <span class="c1"># =&gt; [:spades, :diamonds, :clubs, :hearts]</span>
<span class="no">CardDeck</span><span class="o">::</span><span class="no">NUM_CARDS</span> <span class="c1"># =&gt; raises uninitialized constant error</span>
</code></pre></div>
<h2 id="use-cases">Use Cases</h2>

<p>I've found this useful in a few different situations:</p>

<ul>
  <li>It provides a simple way to change a class setting expressed as
a constant for one test. In the past, I've often defined static
class methods just so they could be stubbed, even though it
made more sense to use a constant. Now you can just use a constant!</li>
  <li>It makes dependency injection easy when the class-under-test
depends on a collaborator's class method (e.g. when the collaborator
is stateless). You can easily stub the collaborator's class constant
with a test double.</li>
  <li>It makes stubbing unloaded dependencies dead-simple. Gary
Bernhardt discussed this situation at length in <a href="https://www.destroyallsoftware.com/screencasts/catalog/stubbing-unloaded-dependencies">Destroy all
Software #46</a>.
He mentioned mutating constants as a possible way of stubbing unloaded
dependencies, but recommended against it because of the complexity
of safely managing this. Now that rspec-mocks can do it for you, it's
far less complex, and much, much safer.</li>
</ul>

<p>If you're curious how it all works, check out the <a href="https://github.com/rspec/rspec-mocks/blob/2-11-maintenance/lib/rspec/mocks/stub_const.rb">source on
github</a>.</p>

<div class="footnotes">
  <ol>
    <li id="fn:foot_1">
      <p>Actually, this has been available in <a href="https://github.com/xaviershay/rspec-fire">rspec-fire</a> for a good four months or so. But it's not really a full mocking library…it builds on top of rspec-mocks, and now this functionality has been ported over to rspec-mocks. <a href="#fnref:foot_1" class="reversefootnote">&#8617;</a></p>
    </li>
  </ol>
</div>
<div id="disqus_thread"></div>
<script type="text/javascript">
  /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
  var disqus_shortname  = 'myronmarston-personal-site';
  var disqus_identifier = '/n/dev-blog/2012/06/constant-stubbing-in-rspec-2-11';
  var disqus_title      = 'Constant Stubbing in RSpec 2.11';
  var disqus_url        = 'http://myronmars.to/n/dev-blog/2012/06/constant-stubbing-in-rspec-2-11';

  /* * * DON'T EDIT BELOW THIS LINE * * */
  (function() {
      var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
      dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
      (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
  })();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
</article></section><footer><div>Created with the assistance of Ninefold<img alt="Brutus" src="/images/brutus-half.png" /></div><br /><a href="https://dnsimple.link/resolving-rspec" target="_blank">Resolving with<br /><img alt="DNSimple" style="width:100px;" src="https://cdn.dnsimple.com/assets/resolving-with-us/logo-dark.png" /></a></footer><script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-59095215-1', 'auto');
  ga('send', 'pageview');

</script>
<script>
  var SeedAndDewConfig = {};
  (function() {
    SeedAndDewConfig['adClass'] = "snd-ad";
    /* * * DON'T EDIT BELOW THIS LINE * * */
    SeedAndDewConfig['projectId'] = 'ef35b4ec-231e-4950-bd93-4c06fe3b2543';
    SeedAndDewConfig['loadStartTime'] = performance.now();
    SeedAndDewConfig['apiVersion'] = '2018-05-28'
    SeedAndDewConfig['sessionId'] = Math.random().toString(36).substring(2, 15);
    var snd = document.createElement('script');
    snd.type = 'text/javascript';
    snd.async = true;
    snd.src = 'https://www.seedanddew.com/static/embed.min.js';
    (document.getElementsByTagName('head')[0] ||
    document.getElementsByTagName('body')[0]).appendChild(snd);
  })();
</script>
</body><script src="/javascripts/asciinema-player.js"></script></html>