Modified: buildr/site/releasing.html URL: http://svn.apache.org/viewvc/buildr/site/releasing.html?rev=1540236&r1=1540235&r2=1540236&view=diff ============================================================================== --- buildr/site/releasing.html (original) +++ buildr/site/releasing.html Sat Nov 9 01:20:57 2013 @@ -79,7 +79,7 @@ </ol> </div> <div id='content'> - <h1 id='releasing'>Releasing</h1> + <h1 id='Liquid error: wrong number of arguments (1 for 2)'>Releasing</h1> <ol class="toc"><li><a href="#default">What does a release do?</a></li><li><a href="#custom_version">How to specify my own version number scheme?</a></li><li><a href="#custom_tag_and_msg">How to specify my own tag name and commit message?</a></li></ol> <p>Now that we built and tested our awesome software, let’s tell the world and release it.</p> <p>Each buildfile can specify the current version with a constant named <code>VERSION_NUMBER</code> or <code>THIS_VERSION</code>.</p> @@ -91,7 +91,9 @@ <span class="c1"># ...</span> <span class="k">end</span> -</code></pre></div><h2 id="default">What does a release do?</h2> +</code></pre> +</div> +<h2 id="default">What does a release do?</h2> <p>The default behavior of the <code>Release</code> task is the following:</p> <ol> <li>Check that the version to be released and the next version are different</li> @@ -110,12 +112,16 @@ So, at the end of a release, the buildfi <span class="c1"># ...</span> <span class="k">end</span> -</code></pre></div><p>And the Git repository now contains two new commits and a new tag.</p> +</code></pre> +</div> +<p>And the Git repository now contains two new commits and a new tag.</p> <div class="highlight"><pre><code class="sh">~/w/killer-app<span class="o">[</span>master<span class="o">]</span><span class="nv">$git</span> ol -4 c1af3d5 <span class="o">(</span>HEAD, origin/master, master<span class="o">)</span> Changed version number to 1.0.1-SNAPSHOT dd35015 <span class="o">(</span>tag: 1.0.0<span class="o">)</span> Changed version number to 1.0.0 76c96e7 Last fix before the release -</code></pre></div><h2 id="custom_version">How to specify my own version number scheme?</h2> +</code></pre> +</div> +<h2 id="custom_version">How to specify my own version number scheme?</h2> <p>If <code>THIS_VERSION</code> does not contain <code>-SNAPSHOT</code>, Buildr delegates the resolution of the next version number to the user which has 2 differents ways to express her wishes: <code>Release.next_version</code> or the environment variable <code>NEXT_VERSION</code>.</p> <h3 id="next_version_proc">Using Release.next_version</h3> <p>The <code>Release</code> class can receive the next version of the buildfile. This could be a string or a proc that would receive the current version and return the next version.</p> @@ -126,7 +132,7 @@ dd35015 <span class="o">(</span>tag: 1. <span class="c1"># or a proc - equivalent result</span> <span class="no">Release</span><span class="o">.</span><span class="n">next_version</span> <span class="o">=</span> <span class="nb">lambda</span> <span class="k">do</span> <span class="o">|</span><span class="n">this_version</span><span class="o">|</span> <span class="c1"># 2.0.0-SNAPSHOT</span> - <span class="n">new_version</span> <span class="o">=</span> <span class="no">THIS_VERSION</span><span class="o">.</span><span class="n">split</span> <span class="sr">/\./</span> + <span class="n">new_version</span> <span class="o">=</span> <span class="no">THIS_VERSION</span><span class="o">.</span><span class="n">split</span><span class="sr"> /\./</span> <span class="n">new_version</span><span class="o">[</span><span class="mi">0</span><span class="o">]</span> <span class="o">=</span> <span class="n">new_version</span><span class="o">[</span><span class="mi">0</span><span class="o">].</span><span class="n">to_i</span> <span class="o">+</span> <span class="mi">1</span> <span class="n">new_version</span><span class="o">[</span><span class="mi">1</span><span class="o">]</span> <span class="o">=</span> <span class="mi">0</span> <span class="n">new_version</span><span class="o">[</span><span class="mi">2</span><span class="o">]</span> <span class="o">=</span> <span class="s1">'0-SNAPSHOT'</span> @@ -139,14 +145,18 @@ dd35015 <span class="o">(</span>tag: 1. <span class="c1"># ...</span> <span class="k">end</span> -</code></pre></div><h3 id="next_version_envvar">Using the environment variable NEXT_VERSION</h3> +</code></pre> +</div> +<h3 id="next_version_envvar">Using the environment variable NEXT_VERSION</h3> <p>If the environment variable <code>NEXT_VERSION</code> is set, Buildr will use this value to update <code>THIS_VERSION</code> at the end of the release.</p> <p>For conveniency, this variable is case insensitive.</p> <p>So, all 3 following commands will run a release with a custom new version:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr release <span class="nv">next_version</span><span class="o">=</span><span class="s2">"1.0.0-rc1"</span> <span class="nv">$ </span>env <span class="nv">next_version</span><span class="o">=</span><span class="s2">"1.0.0-rc1"</span> buildr release <span class="nv">$ </span>env <span class="nv">NEXT_VERSION</span><span class="o">=</span><span class="s2">"1.0.0-rc1"</span> buildr release -</code></pre></div><p>Those commands will generate the Buildfile below:</p> +</code></pre> +</div> +<p>Those commands will generate the Buildfile below:</p> <div class="highlight"><pre><code class="ruby"><span class="no">THIS_VERSION</span> <span class="o">=</span> <span class="s2">"1.0.0-rc1"</span> <span class="n">define</span> <span class="s1">'killer-app'</span> <span class="k">do</span> @@ -155,7 +165,9 @@ dd35015 <span class="o">(</span>tag: 1. <span class="c1"># ...</span> <span class="k">end</span> -</code></pre></div><p>The environment variable <code>NEXT_VERSION</code> has precedence over Release.next_version.</p> +</code></pre> +</div> +<p>The environment variable <code>NEXT_VERSION</code> has precedence over Release.next_version.</p> <h2 id="custom_tag_and_msg">How to specify my own tag name and commit message?</h2> <p>As explained earlier, Buildr will create two new commits and a new tag in the version control system. Similarly to <code>Release.next_version</code>, the commit message and the tag name can be customized with <code>Release.message</code> and <code>Release.tag_name</code>. Both could be strings or procs that would receive the released version <code>THIS_VERSION</code> without <code>-SNAPSHOT</code>.</p> </div>
Modified: buildr/site/settings_profiles.html URL: http://svn.apache.org/viewvc/buildr/site/settings_profiles.html?rev=1540236&r1=1540235&r2=1540236&view=diff ============================================================================== --- buildr/site/settings_profiles.html (original) +++ buildr/site/settings_profiles.html Sat Nov 9 01:20:57 2013 @@ -79,19 +79,25 @@ </ol> </div> <div id='content'> - <h1 id='settings/profiles'>Settings/Profiles</h1> + <h1 id='Liquid error: wrong number of arguments (1 for 2)'>Settings/Profiles</h1> <ol class="toc"><li><a href="#env_vars">Environment Variables</a></li><li><a href="#personal">Personal Settings</a></li><li><a href="#build">Build Settings</a></li><li><a href="#variable">Non constant settings</a></li><li><a href="#environments">Environments</a></li><li><a href="#profiles">Profiles</a></li></ol> <h2 id="env_vars">Environment Variables</h2> <p>Buildr uses several environment variables that help you control how it works. Some environment variables you will only set once or change infrequently. You can set these in your profile, OS settings or any tool you use to launch Buildr (e.g. continuous integration).</p> <p>For example:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span><span class="nb">export </span><span class="nv">HTTP_PROXY</span><span class="o">=</span>http://myproxy:8080 -</code></pre></div><p>There are other environment variables you will want to set when running Buildr, for example, to do a full build without running the tests:</p> +</code></pre> +</div> +<p>There are other environment variables you will want to set when running Buildr, for example, to do a full build without running the tests:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr <span class="nb">test</span><span class="o">=</span>no -</code></pre></div><p>For convenience, the environment variables <code>TEST</code> and <code>DEBUG</code> are case insensitive, you can use either <code>test=no</code> or <code>TEST=no</code>. Any other environment variable names are case sensitive.</p> +</code></pre> +</div> +<p>For convenience, the environment variables <code>TEST</code> and <code>DEBUG</code> are case insensitive, you can use either <code>test=no</code> or <code>TEST=no</code>. Any other environment variable names are case sensitive.</p> <p>You can also set environment variables from within your Buildfile. For example, if you discover that building your project requires gobs of <span class="caps">JVM</span> heap space, and you want all other team members to run with the same settings:</p> <div class="highlight"><pre><code class="ruby"><span class="c1"># This project builds a lot of code.</span> <span class="no">ENV</span><span class="o">[</span><span class="s1">'JAVA_OPTS'</span><span class="o">]</span> <span class="o">||=</span> <span class="s1">'-Xms1g -Xmx1g'</span> -</code></pre></div><p>Make sure to set any environment variables at the very top of the Buildfile, above any Ruby statement (even <code>require</code>).</p> +</code></pre> +</div> +<p>Make sure to set any environment variables at the very top of the Buildfile, above any Ruby statement (even <code>require</code>).</p> <p class="tip">Using <code>||=</code> sets the environment variable, if not already set, so it’s still possible for other developers to override this environment variable without modifying the Buildfile.</p> <p>Buildr supports the following environment variables:</p> <table> @@ -152,7 +158,10 @@ <p>Some extensions may use additional environment variables, and of course, you can always add your own. This example uses two environment variables for specifying the username and password:</p> <div class="highlight"><pre><code class="ruby"><span class="n">repositories</span><span class="o">.</span><span class="n">release_to</span><span class="o">[</span><span class="ss">:username</span><span class="o">]</span> <span class="o">=</span> <span class="no">ENV</span><span class="o">[</span><span class="s1">'USERNAME'</span><span class="o">]</span> <span class="n">repositories</span><span class="o">.</span><span class="n">release_to</span><span class="o">[</span><span class="ss">:password</span><span class="o">]</span> <span class="o">=</span> <span class="no">ENV</span><span class="o">[</span><span class="s1">'PASSWORD'</span><span class="o">]</span> -</code></pre></div><h2 id="personal">Personal Settings</h2> +</code></pre> +</div> +<p>The same works for the <code>repositories.snapshot_to</code> hash.</p> +<h2 id="personal">Personal Settings</h2> <p>Some things clearly do not belong in the Buildfile. For example, the username and password you use to upload releases. If you’re working in a team or on an open source project, you’d want to keep these in a separate place.</p> <p>You may want to use personal settings for picking up a different location for the local repository, or use a different set of preferred remote repositories, and so forth.</p> <p>The prefered way to store personal settings is to create a <code>.buildr/settings.yaml</code> file under your home directory. Settings stored there will be applied the same across all builds.</p> @@ -179,13 +188,17 @@ <span class="l-Scalar-Plain">server</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">jabber.company.com</span> <span class="l-Scalar-Plain">usr</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">[email protected]</span> <span class="l-Scalar-Plain">pwd</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">secret</span> -</code></pre></div><p>Later your buildfile or addons can reference user preferences using the hash returned by the <code>Buildr.settings.user</code> accessor.</p> +</code></pre> +</div> +<p>Later your buildfile or addons can reference user preferences using the hash returned by the <code>Buildr.settings.user</code> accessor.</p> <div class="highlight"><pre><code class="ruby"><span class="n">task</span> <span class="s1">'release-notification'</span> <span class="k">do</span> <span class="n">usr</span><span class="p">,</span> <span class="n">pwd</span><span class="p">,</span> <span class="n">server</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">user</span><span class="o">[</span><span class="s1">'im'</span><span class="o">].</span><span class="n">values_at</span><span class="p">(</span><span class="s1">'usr'</span><span class="p">,</span> <span class="s1">'pwd'</span><span class="p">,</span> <span class="s1">'server'</span><span class="p">)</span> <span class="n">jabber</span> <span class="o">=</span> <span class="no">JabberAPI</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="n">server</span><span class="p">,</span> <span class="n">usr</span><span class="p">,</span> <span class="n">pwd</span><span class="p">)</span> <span class="n">jabber</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">"We are pleased to announce the last stable version </span><span class="si">#{</span><span class="no">VERSION</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span> <span class="k">end</span> -</code></pre></div><h2 id="build">Build Settings</h2> +</code></pre> +</div> +<h2 id="build">Build Settings</h2> <p>Build settings are local to the project being built, and are placed in the <code>build.yaml</code> file located in the same directory that the <code>buildfile</code>. Normally this file would be managed by the project revision control system, so settings here are shared between developers.</p> <p>They help keep the buildfile and build.yaml file simple and readable, working to the advantages of each one. Example for build settings are gems, repositories and artifacts used by that build.</p> <div class="highlight"><pre><code class="yaml"><span class="c1"># This project requires the following ruby gems, buildr addons</span> @@ -214,13 +227,17 @@ <span class="l-Scalar-Plain">jira</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">uri</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">https://jira.corp.org</span> -</code></pre></div><p>When buildr is loaded, required ruby gems will be installed if needed, thus adding features like the imaginary twitter notifier addon.</p> +</code></pre> +</div> +<p>When buildr is loaded, required ruby gems will be installed if needed, thus adding features like the imaginary twitter notifier addon.</p> <p>Artifacts defined on <code>build.yaml</code> can be referenced on your buildfile by supplying the ruby symbol to the <code>Buildr.artifact</code> and <code>Buildr.artifacts</code> methods. The <code>compile.with</code>, <code>test.with</code> methods can also be given these names.</p> <div class="highlight"><pre><code class="ruby"><span class="n">define</span> <span class="s1">'my_project'</span> <span class="k">do</span> <span class="n">compile</span><span class="o">.</span><span class="n">with</span> <span class="n">artifacts</span><span class="p">(</span><span class="ss">:log4j</span><span class="p">,</span> <span class="ss">:j2ee</span><span class="p">)</span> <span class="nb">test</span><span class="o">.</span><span class="n">with</span> <span class="ss">:spring</span><span class="p">,</span> <span class="ss">:j2ee</span> <span class="k">end</span> -</code></pre></div><p>Build settings can be retreived using the <code>Buildr.settings.build</code> accessor.</p> +</code></pre> +</div> +<p>Build settings can be retreived using the <code>Buildr.settings.build</code> accessor.</p> <div class="highlight"><pre><code class="ruby"> <span class="n">task</span> <span class="s1">'create_patch'</span> <span class="k">do</span> <span class="n">patch</span> <span class="o">=</span> <span class="no">Git</span><span class="o">.</span><span class="n">create_patch</span> <span class="ss">:interactive</span> <span class="o">=></span> <span class="kp">true</span> <span class="k">if</span> <span class="n">patch</span> <span class="o">&&</span> <span class="n">agree</span><span class="p">(</span><span class="s2">"Would you like to request inclusion of </span><span class="si">#{</span><span class="n">patch</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span> @@ -228,7 +245,9 @@ <span class="n">jira</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="ss">:improvement</span><span class="p">,</span> <span class="n">patch</span><span class="o">.</span><span class="n">summary</span><span class="p">,</span> <span class="ss">:attachment</span> <span class="o">=></span> <span class="n">patch</span><span class="o">.</span><span class="n">blob</span><span class="p">)</span> <span class="k">end</span> <span class="k">end</span> -</code></pre></div><h2 id="variable">Non constant settings</h2> +</code></pre> +</div> +<h2 id="variable">Non constant settings</h2> <p>Before loading the Buildfile, Buildr will attempt to load two other files: the <code>buildr.rb</code> file in the <code>.buildr</code> directory under your home directory, followed by the <code>_buildr.rb</code> (or <code>.buildr.rb</code>) file it finds in the build directory.</p> <p>The loading order allows you to place global settings that affect all your builds in your <code>buildr.rb</code>, but also over-ride those with settings for a given project.</p> <p>Here’s an example <code>buildr.rb</code>:</p> @@ -237,25 +256,35 @@ <span class="n">repositories</span><span class="o">.</span><span class="n">release_to</span><span class="o">[</span><span class="ss">:password</span><span class="o">]</span> <span class="o">=</span> <span class="s1">'supersecret'</span> <span class="c1"># Search here first, it's faster</span> <span class="n">repositories</span><span class="o">.</span><span class="n">remote</span> <span class="o"><<</span> <span class="s1">'http://inside-the-firewall'</span> -</code></pre></div><p class="note">Buildr 1.3 and earlier used the file <code>buildr.rb</code> directly in your home directory. Starting with version 1.4, Buildr loads <code>buildr.rb</code> from the <code>.buildr</code> directory under your home directory in preference. If you use Buildr 1.3 and earlier and don’t want to duplicate your settings, you can move you existing <code>buildr.rb</code> under the <code>.buildr</code> directory and create a new <code>buildr.rb</code> in your home directory containing:</p> +</code></pre> +</div> +<p class="note">Buildr 1.3 and earlier used the file <code>buildr.rb</code> directly in your home directory. Starting with version 1.4, Buildr loads <code>buildr.rb</code> from the <code>.buildr</code> directory under your home directory in preference. If you use Buildr 1.3 and earlier and don’t want to duplicate your settings, you can move you existing <code>buildr.rb</code> under the <code>.buildr</code> directory and create a new <code>buildr.rb</code> in your home directory containing:</p> <div class="highlight"><pre><code class="ruby"><span class="c1"># Backward compatibility: Buildr 1.4+ uses $HOME/.buildr/buildr.rb</span> <span class="nb">load</span> <span class="no">File</span><span class="o">.</span><span class="n">expand_path</span><span class="p">(</span><span class="s1">'buildr.rb'</span><span class="p">,</span> <span class="no">Buildr</span><span class="o">.</span><span class="n">application</span><span class="o">.</span><span class="n">home_dir</span><span class="p">)</span> -</code></pre></div><h2 id="environments">Environments</h2> +</code></pre> +</div> +<h2 id="environments">Environments</h2> <p>One common use case is adapting the build to different environments. For example, to compile code with debugging information during development and testing, but strip it for production. Another example is using different databases for development, testing and production, or running services at different URLs.</p> <p>So let’s start by talking about the build environment. Buildr has a global attributes that indicates which environment it’s running in, accessible from the <code>environment</code> method. You can set the current build environment in one of two ways. Using the <code>-e/--environment</code> command line option:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr -e <span class="nb">test</span> <span class="o">(</span>in /home/john/project, <span class="nb">test</span><span class="o">)</span> -</code></pre></div><p>Or by setting the environment variable <code>BUILDR_ENV</code>:</p> +</code></pre> +</div> +<p>Or by setting the environment variable <code>BUILDR_ENV</code>:</p> <div class="highlight"><pre><code class="text">$ export BUILDR_ENV=production $ buildr (in /home/john/project, production) -</code></pre></div><p>Unless you tell it otherwise, Buildr assumes you’re developing and sets the environment to <code>development</code>.</p> +</code></pre> +</div> +<p>Unless you tell it otherwise, Buildr assumes you’re developing and sets the environment to <code>development</code>.</p> <p>Here’s a simple example for handling different environments within the Buildfile:</p> <div class="highlight"><pre><code class="ruby"><span class="n">project</span> <span class="s1">'db-module'</span> <span class="k">do</span> <span class="n">db</span> <span class="o">=</span> <span class="p">(</span><span class="no">Buildr</span><span class="o">.</span><span class="n">environment</span> <span class="o">==</span> <span class="s1">'production'</span> <span class="p">?</span> <span class="s1">'oracle'</span> <span class="p">:</span> <span class="s1">'hsql'</span><span class="p">)</span> <span class="n">resources</span><span class="o">.</span><span class="n">from</span><span class="p">(</span><span class="n">_</span><span class="p">(</span><span class="s2">"src/main/</span><span class="si">#{</span><span class="n">db</span><span class="si">}</span><span class="s2">"</span><span class="p">))</span> <span class="k">end</span> -</code></pre></div><p>We recommend picking a convention for your different environments and following it across all your projects. For example:</p> +</code></pre> +</div> +<p>We recommend picking a convention for your different environments and following it across all your projects. For example:</p> <table> <tr> <th>Environment </th> @@ -292,7 +321,9 @@ $ buildr <span class="l-Scalar-Plain">production</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">db</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">oracle</span> <span class="l-Scalar-Plain">jdbc</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">oracle:thin:@bigstrong:1521:mighty</span> -</code></pre></div><p>Here’s a simple example for a buildfile that uses the profile information:</p> +</code></pre> +</div> +<p>Here’s a simple example for a buildfile that uses the profile information:</p> <div class="highlight"><pre><code class="ruby"><span class="n">project</span> <span class="s1">'db-module'</span> <span class="k">do</span> <span class="c1"># Copy SQL files specific for the database we're using,</span> <span class="c1"># for example, everything under src/main/hsql.</span> @@ -300,7 +331,9 @@ $ buildr <span class="c1"># Set the JDBC URL in copied resource files (config.xml needs this).</span> <span class="n">resources</span><span class="o">.</span><span class="n">filter</span><span class="o">.</span><span class="n">using</span> <span class="ss">:jdbc</span><span class="o">=></span><span class="no">Buildr</span><span class="o">.</span><span class="n">settings</span><span class="o">.</span><span class="n">profile</span><span class="o">[</span><span class="s1">'jdbc'</span><span class="o">]</span> <span class="k">end</span> -</code></pre></div><p>The <code>profile</code> method returns the current profile, selected based on the current <a href="#environments">environment</a>. You can get a list of all profiles by calling <code>profiles</code>.</p> +</code></pre> +</div> +<p>The <code>profile</code> method returns the current profile, selected based on the current <a href="#environments">environment</a>. You can get a list of all profiles by calling <code>profiles</code>.</p> <p>When you run the above example in <code>development</code>, the current profile will return the hash <code>{ 'db'=>'hsql', 'jdbc'=>'hsqldb:mem:devdb' }</code>.</p> <p>We recommend following conventions and using the same environments in all your projects, but sometimes the profiles end up being the same, so here’s a trick you can use to keep your profiles <span class="caps">DRY</span>.</p> <p><span class="caps">YAML</span> allows you to use anchors (<code>&</code>), similar to ID attributes in <span class="caps">XML</span>, reference the anchored element (<code>*</code>) elsewhere, and merge one element into another (<code><<</code>). For example:</p> @@ -314,7 +347,9 @@ $ buildr <span class="l-Scalar-Plain">test</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain"><<</span><span class="p-Indicator">:</span> <span class="nv">*common</span> <span class="l-Scalar-Plain">jdbc</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">hsqldb:file:testdb</span> -</code></pre></div><p>You can <a href="http://www.yaml.org";>learn more about <span class="caps">YAML</span> here</a>, and use this handy <a href="http://www.yaml.org/refcard.html";><span class="caps">YAML</span> quick reference</a>.</p> +</code></pre> +</div> +<p>You can <a href="http://www.yaml.org";>learn more about <span class="caps">YAML</span> here</a>, and use this handy <a href="http://www.yaml.org/refcard.html";><span class="caps">YAML</span> quick reference</a>.</p> </div> <div id='footer'>Copyright © 2007-2010 The Apache Software Foundation</div> </div> Modified: buildr/site/testing.html URL: http://svn.apache.org/viewvc/buildr/site/testing.html?rev=1540236&r1=1540235&r2=1540236&view=diff ============================================================================== --- buildr/site/testing.html (original) +++ buildr/site/testing.html Sat Nov 9 01:20:57 2013 @@ -79,7 +79,7 @@ </ol> </div> <div id='content'> - <h1 id='testing'>Testing</h1> + <h1 id='Liquid error: wrong number of arguments (1 for 2)'>Testing</h1> <ol class="toc"><li><a href="#writing">Writing Tests</a></li><li><a href="#ignoring">Excluding Tests and Ignoring Failures</a></li><li><a href="#running">Running Tests</a></li><li><a href="#integration">Integration Tests</a></li><li><a href="#setup_teardown">Using Setup and Teardown</a></li><li><a href="#checks">Testing Your Build</a></li><li><a href="#bdd">Behaviour-Driven Development</a></li></ol> <p>Untested code is broken code, so we take testing seriously. Off the bat you get to use either JUnit or TestNG for writing unit tests and integration tests. And you can also add your own framework, or even script tests using Ruby. But first, let’s start with the basics.</p> <h2 id="writing">Writing Tests</h2> @@ -92,61 +92,99 @@ <h2 id="ignoring">Excluding Tests and Ignoring Failures</h2> <p>If you have a lot of tests that are failing or just hanging there collecting dusts, you can tell Buildr to ignore them. You can either tell Buildr to only run specific tests, for example:</p> <div class="highlight"><pre><code class="ruby"><span class="nb">test</span><span class="o">.</span><span class="n">include</span> <span class="s1">'com.acme.tests.passing.*'</span> -</code></pre></div><p>Or tell it to exclude specific tests, for example:</p> +</code></pre> +</div> +<p>Or tell it to exclude specific tests, for example:</p> <div class="highlight"><pre><code class="ruby"><span class="nb">test</span><span class="o">.</span><span class="n">exclude</span> <span class="s1">'*FailingTest'</span><span class="p">,</span> <span class="s1">'*FailingWorseTest'</span> -</code></pre></div><p>Note that we’re always using the package qualified class name, and you can use star (<code>*</code>) to substitute for any set of characters.</p> +</code></pre> +</div> +<p>Note that we’re always using the package qualified class name, and you can use star (<code>*</code>) to substitute for any set of characters.</p> <p>When tests fail, Buildr fails the <code>test</code> task. This is usually a good thing, but you can also tell Buildr to ignore failures by resetting the <code>:fail_on_failure</code> option:</p> <div class="highlight"><pre><code class="ruby"><span class="nb">test</span><span class="o">.</span><span class="n">using</span> <span class="ss">:fail_on_failure</span><span class="o">=></span><span class="kp">false</span> -</code></pre></div><p>Besides giving you a free pass to ignore failures, you can use it for other causes, for example, as a gentle reminder:</p> +</code></pre> +</div> +<p>Besides giving you a free pass to ignore failures, you can use it for other causes, for example, as a gentle reminder:</p> <div class="highlight"><pre><code class="ruby"><span class="nb">test</span> <span class="k">do</span> <span class="nb">warn</span> <span class="s2">"Did you forget something?"</span> <span class="k">if</span> <span class="nb">test</span><span class="o">.</span><span class="n">tests</span><span class="o">.</span><span class="n">nil?</span> <span class="o">||</span> <span class="nb">test</span><span class="o">.</span><span class="n">tests</span><span class="o">.</span><span class="n">empty?</span> <span class="k">end</span> -</code></pre></div><p>The <code>tests</code> collection holds the names of all classes with tests, if any. And there’s <code>classes</code>, which holds the names of all test classes. We’ll let you imagine creative use for these two.</p> +</code></pre> +</div> +<p>The <code>tests</code> collection holds the names of all classes with tests, if any. And there’s <code>classes</code>, which holds the names of all test classes. We’ll let you imagine creative use for these two.</p> <h2 id="running">Running Tests</h2> <p>It’s a good idea to run tests every time you change the source code, so we wired the <code>build</code> task to run the <code>test</code> task at the end of the build. And conveniently enough, the <code>build</code> task is the default task, so another way to build changes in your code and run your tests:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr -</code></pre></div><p>That only works with the local <code>build</code> task and any local task that depends on it, like <code>package</code>, <code>install</code> and <code>upload</code>. Each project also has its own <code>build</code> task that does not invoke the <code>test</code> task, so <code>buildr build</code> will run the tests cases, but <code>buildr foo:build</code> will not.</p> +</code></pre> +</div> +<p>That only works with the local <code>build</code> task and any local task that depends on it, like <code>package</code>, <code>install</code> and <code>upload</code>. Each project also has its own <code>build</code> task that does not invoke the <code>test</code> task, so <code>buildr build</code> will run the tests cases, but <code>buildr foo:build</code> will not.</p> <p>While it’s a good idea to always run your tests, it’s not always possible. There are two ways you can get <code>build</code> to not run the <code>test</code> task. You can set the environment variable <code>test</code> to <code>no</code> (but <code>skip</code> and <code>off</code> will also work). You can do that when running Buildr:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr <span class="nb">test</span><span class="o">=</span>no -</code></pre></div><p>Or set it once in your environment:</p> +</code></pre> +</div> +<p>Or set it once in your environment:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span><span class="nb">export </span><span class="nv">TEST</span><span class="o">=</span>no <span class="nv">$ </span>buildr -</code></pre></div><p>If you’re feeling really adventurous, you can also disable tests from your Buildfile or <code>buildr.rb</code> file, by setting <code>options.test = false</code>. We didn’t say it’s a good idea, we’re just giving you the option.</p> +</code></pre> +</div> +<p>If you’re feeling really adventurous, you can also disable tests from your Buildfile or <code>buildr.rb</code> file, by setting <code>options.test = false</code>. We didn’t say it’s a good idea, we’re just giving you the option.</p> <p>The <code>test</code> task is just smart enough to run all the tests it finds, but will accept include/exclude patterns. Often enough you’re only working on one broken test and you only want to run that one test. Better than changing your Buildfile, you can run the <code>test</code> task with a pattern. For example:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr <span class="nb">test</span>:KillerAppTest -</code></pre></div><p>Buildr will then run only tests that match the pattern <code>KillerAppTest</code>. It uses pattern matching, so <code>test:Foo</code> will run <code>com.acme.FooTest</code> and <code>com.acme.FooBarTest</code>. With Java, you can use this to pick a class name, or a package name to run all tests in that package, or any such combination. In fact, you can specify several patterns separated with commas. For example:</p> +</code></pre> +</div> +<p>Buildr will then run only tests that match the pattern <code>KillerAppTest</code>. It uses pattern matching, so <code>test:Foo</code> will run <code>com.acme.FooTest</code> and <code>com.acme.FooBarTest</code>. With Java, you can use this to pick a class name, or a package name to run all tests in that package, or any such combination. In fact, you can specify several patterns separated with commas. For example:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr <span class="nb">test</span>:FooTest,BarTest -</code></pre></div><p>Buildr forcefully runs all tests that match the pattern. If you want to re-run all tests even if your sources have not changed, you can execute:</p> +</code></pre> +</div> +<p>Buildr forcefully runs all tests that match the pattern. If you want to re-run all tests even if your sources have not changed, you can execute:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr <span class="nb">test</span>:* -</code></pre></div><p>You can exclude tests by preceeding them with a minus sign (‘-’):</p> +</code></pre> +</div> +<p>You can exclude tests by preceeding them with a minus sign (‘-’):</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr <span class="nb">test</span>:-Bar -</code></pre></div><p>The above would run all tests except those with a name containing <code>Bar</code>. Exclusions can be combined with inclusions:</p> +</code></pre> +</div> +<p>The above would run all tests except those with a name containing <code>Bar</code>. Exclusions can be combined with inclusions:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr <span class="nb">test</span>:Foo,-Bar -</code></pre></div><p>Buildr would then run tests with names containing <code>Foo</code> but not <code>Bar</code>.</p> +</code></pre> +</div> +<p>Buildr would then run tests with names containing <code>Foo</code> but not <code>Bar</code>.</p> <p>As you probably noticed, Buildr will stop your build at the first test that fails. We think it’s a good idea, except when it’s not. If you’re using a continuous build system, you’ll want a report of all the failed tests without stopping at the first failure. To make that happen, set the environment variable <code>test</code> to “all”, or the Buildr <code>options.test</code> option to <code>:all</code>. For example:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr package <span class="nb">test</span><span class="o">=</span>all -</code></pre></div><p>We’re using <code>package</code> and not <code>build</code> above. When using a continuous build system, you want to make sure that packages are created, contain the right files, and also run the integration tests.</p> +</code></pre> +</div> +<p>We’re using <code>package</code> and not <code>build</code> above. When using a continuous build system, you want to make sure that packages are created, contain the right files, and also run the integration tests.</p> <p>During development, if you want to re-run only tests that have failed during the last test execution, you can execute:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr <span class="nb">test</span>:failed -</code></pre></div><p>One last note on running tests. By default when you run tests, Buildr will automatically run all transitive test dependencies. This mean if you run “buildr test” inside project <code>bar</code> and <code>bar</code> depends on project <code>foo</code>, Buildr will first run tests in project <code>foo</code> if there have been any changes affecting <code>foo</code> that haven’t been taken into account yet. This behavior often surprises people, especially when they are trying to get things done and only care about tests in <code>bar</code> at that moment. For those times when you’d like to focus your testing on specific projects, Buildr has the <code>only</code> option that will only run tests for projects specified on the command line,</p> +</code></pre> +</div> +<p>One last note on running tests. By default when you run tests, Buildr will automatically run all transitive test dependencies. This mean if you run “buildr test” inside project <code>bar</code> and <code>bar</code> depends on project <code>foo</code>, Buildr will first run tests in project <code>foo</code> if there have been any changes affecting <code>foo</code> that haven’t been taken into account yet. This behavior often surprises people, especially when they are trying to get things done and only care about tests in <code>bar</code> at that moment. For those times when you’d like to focus your testing on specific projects, Buildr has the <code>only</code> option that will only run tests for projects specified on the command line,</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr <span class="nb">test</span><span class="o">=</span>only bar:test -</code></pre></div><h2 id="integration">Integration Tests</h2> +</code></pre> +</div> +<h2 id="integration">Integration Tests</h2> <p>So far we talked about unit tests. Unit tests are run in isolation on the specific project they test, in an isolated environment, generally with minimal setup and teardown. You get a sense of that when we told you tests run after the <code>build</code> task, and include JMock in the dependency list.</p> <p>In contrast, integration tests are run with a number of components, in an environment that resembles production, often with more complicates setup and teardown procedures. In this section we’ll talk about the differences between running unit and integration tests.</p> <p>You write integration tests much the same way as you write unit tests, using <code>test.compile</code> and <code>test.resources</code>. However, you need to tell Buildr that your tests will execute during integration test. To do so, add the following line in your project definition:</p> <div class="highlight"><pre><code class="ruby"><span class="nb">test</span><span class="o">.</span><span class="n">using</span> <span class="ss">:integration</span> -</code></pre></div><p>Typically you’ll use unit tests in projects that create internal modules, such as JARs, and integration tests in projects that create components, such as WARs and EARs. You only need to use the <code>:integration</code> option with the later.</p> +</code></pre> +</div> +<p>Typically you’ll use unit tests in projects that create internal modules, such as JARs, and integration tests in projects that create components, such as WARs and EARs. You only need to use the <code>:integration</code> option with the later.</p> <p>To run integration tests on the current project:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr integration -</code></pre></div><p>You can also run specific tests cases, for example:</p> +</code></pre> +</div> +<p>You can also run specific tests cases, for example:</p> <div class="highlight"><pre><code class="sh"><span class="nv">$ </span>buildr integration:ClientTest -</code></pre></div><p>If you run the <code>package</code> task (or any task that depends on it, like <code>install</code> and <code>upload</code>), Buildr will first run the <code>build</code> task and all its unit tests, and then create the packages and run the integration tests. That gives you full coverage for your tests and ready to release packages. As with unit tests, you can set the environment variable <code>test</code> to “no” to skip integration tests, or “all” to ignore failures.</p> +</code></pre> +</div> +<p>If you run the <code>package</code> task (or any task that depends on it, like <code>install</code> and <code>upload</code>), Buildr will first run the <code>build</code> task and all its unit tests, and then create the packages and run the integration tests. That gives you full coverage for your tests and ready to release packages. As with unit tests, you can set the environment variable <code>test</code> to “no” to skip integration tests, or “all” to ignore failures.</p> <h2 id="setup_teardown">Using Setup and Teardown</h2> <p>Some tests need you to setup an environment before they run, and tear it down afterwards. The test frameworks (JUnit, TestNG) allow you to do that for each test. Buildr provides two additional mechanisms for dealing with more complicated setup and teardown procedures.</p> <p>Integration tests run a setup task before the tests, and a teardown task afterwards. You can use this task to setup a Web server for testing your Web components, or a database server for testing persistence. You can access either task by calling <code>integration.setup</code> and <code>integration.teardown</code>. For example:</p> <div class="highlight"><pre><code class="ruby"><span class="n">integration</span><span class="o">.</span><span class="n">setup</span> <span class="p">{</span> <span class="n">server</span><span class="o">.</span><span class="n">start</span> <span class="p">;</span> <span class="n">server</span><span class="o">.</span><span class="n">deploy</span> <span class="p">}</span> <span class="n">integration</span><span class="o">.</span><span class="n">teardown</span> <span class="p">{</span> <span class="n">server</span><span class="o">.</span><span class="n">stop</span> <span class="p">}</span> -</code></pre></div><p>Depending on your build, you may want to enhance the setup/teardown tasks from within a project, for example, to populate the database with data used by that project’s test, or from outside the project definition, for example, to start and stop the Web server.</p> +</code></pre> +</div> +<p>Depending on your build, you may want to enhance the setup/teardown tasks from within a project, for example, to populate the database with data used by that project’s test, or from outside the project definition, for example, to start and stop the Web server.</p> <p>Likewise, each project has its own setup and teardown tasks that are run before and after tests for that specific project. You can access these tasks using <code>test.setup</code> and <code>test.teardown</code>.</p> <h2 id="checks">Testing Your Build</h2> <p>So you got the build running and all the tests pass, binaries are shipping when you find out some glaring omissions. The license file is empty, the localized messages for Japanese are missing, the <span class="caps">CSS</span> files are not where you expect them to be. The fact is, some errors slip by unit and integration tests. So how do we make sure the same mistake doesn’t happen again?</p> @@ -173,12 +211,16 @@ <span class="n">check</span> <span class="n">file</span><span class="p">(</span><span class="s1">'target/classes/killerapp/Code.class'</span><span class="p">),</span> <span class="s1">'should exist'</span> <span class="k">do</span> <span class="n">it</span><span class="o">.</span><span class="n">should</span> <span class="n">exist</span> <span class="k">end</span> -</code></pre></div><p>The first argument is the subject, or the project if you skip the first argument. The second argument is the description, optional, but we recommend using it. The method <code>it</code> returns the subject.</p> +</code></pre> +</div> +<p>The first argument is the subject, or the project if you skip the first argument. The second argument is the description, optional, but we recommend using it. The method <code>it</code> returns the subject.</p> <p>You can also write the first expectation like this:</p> <div class="highlight"><pre><code class="ruby"><span class="n">check</span> <span class="k">do</span> <span class="n">package</span><span class="p">(</span><span class="ss">:jar</span><span class="p">)</span><span class="o">.</span><span class="n">should</span> <span class="n">exist</span> <span class="k">end</span> -</code></pre></div><p>We recommend using the subject and description, they make your build easier to read and maintain, and produce better error messages.</p> +</code></pre> +</div> +<p>We recommend using the subject and description, they make your build easier to read and maintain, and produce better error messages.</p> <p>There are two methods you can call on just about any object, called <code>should</code> and <code>should_not</code>. Each method takes an argument, a matcher, and executes that matcher. If the matcher returns false, <code>should</code> fails. You can figure out what <code>should_not</code> does in the same case.</p> <p>Buildr provides the following matchers:</p> <table>
