- Revision
- 1262
- Author
- mauro
- Date
- 2009-09-19 17:50:10 -0500 (Sat, 19 Sep 2009)
Log Message
Added more advanced topics.
Modified Paths
- trunk/core/distribution/src/site/content/developing-scenarios.html
- trunk/core/distribution/src/site/content/getting-started.html
- trunk/core/distribution/src/site/content/license.html
- trunk/core/distribution/src/site/content/parameter-converters.html
- trunk/core/distribution/src/site/content/parameter-injection.html
- trunk/core/distribution/src/site/content/running-scenarios.html
- trunk/core/distribution/src/site/content/sitemap.xml
- trunk/core/distribution/src/site/content/source-repository.html
Added Paths
Diff
Modified: trunk/core/distribution/src/site/content/developing-scenarios.html (1261 => 1262)
--- trunk/core/distribution/src/site/content/developing-scenarios.html 2009-09-19 20:53:52 UTC (rev 1261) +++ trunk/core/distribution/src/site/content/developing-scenarios.html 2009-09-19 22:50:10 UTC (rev 1262) @@ -9,29 +9,31 @@ <h2>Writing Textual Scenarios</h2> <p>BDD encourages you to start defining the scenarios that express -the desired behaviour in a textual format, e.g.: +the desired behaviour in a textual format, e.g.:</p> <pre class="brush: plain"> Given a stock of symbol STK1 and a threshold of 10.0 When the stock is traded at 5.0 Then the alert status should be OFF When the stock is traded at 11.0 Then the alert status should be ON -</pre>. The textual scenario should use the language of the business domain -and shield away as much as possible the details of the technical +</pre> +<p>The textual scenario should use the language of the business +domain and shield away as much as possible the details of the technical implementation. Also, it should be given a name that is expressive of the functionality that is being verified, i.e. <b>trader_is_alerted_of_status.scenario</b>. </p> <p>The scenario should use a syntax compatible with the <a href="" Grammar</a>.</p> -<h2>Mapping Textual Scenarios to Java</h2> +<h2>Mapping Textual Scenario Steps to Java Methods</h2> -<p>JBehave maps textual steps to Java method via a <a +<p>JBehave maps textual steps to Java methods via a <a href="" class. The scenario writer need only extends the default implementation <a href="" and provide annotated method that match the textual steps by regex -patterns: <pre class="brush: java"> +patterns:</p> +<pre class="brush: java"> public class TraderSteps extends Steps { private Stock stock; @@ -52,13 +54,29 @@ } } -</pre></p> +</pre> +<p>Each type of step has a corresponding JBehave annotation (<a + href="" +<a href="" +<a href="" +each holding a regex pattern as value. The pattern is used to match the +method in the Steps class with the appropriate parameters. The simplest +default behaviour identifies arguments in the candidate step by the +words prefixed by the <b>$</b> character. More advanced <a + href="" injection</a> mechanisms +are also supported by JBehave.</p> +<p>JBehave execute all the matched steps in the order in which they +are found in the Scenario. It is up to the implementor of the Steps +class to provide the logic to tie together the results of the execution +of each step. This can be done by keeping state member variables in the +Steps class or possibly by using a service API or other dependency.</p> -<h2>Running Scenarios</h2> +<h2>Mapping Scenario Files to Java Classes</h2> <p>In JBehave Core scenarios can be run in an automated way via a -one-to-one mapping to Java files. The mechanism via which the textual -scenarios are resolved is determined by the implementation of the <a +one-to-one mapping to Java classes. The mechanism via which the textual +scenarios are resolved from a Java class is determined by the +implementation of the <a href="" In our example, we need to create a file <code>TraderIsAletedOfStatus.java</code>, which maps to out textual scenario in same package.</p> @@ -72,7 +90,8 @@ <p>(Only when running via Maven) Must provide an additional constructor with a ClassLoader parameter.</p> -<p>Thus in our case the example Scenario would look like: <pre class="brush: java"> +<p>Thus in our case the example Scenario would look like:</p> +<pre class="brush: java"> public class TraderIsAletedOfStatus extends JUnitScenario { public TraderIsAletedOfStatus() { @@ -89,13 +108,14 @@ } } -</pre></p> +</pre> + <p>Here we are configuring our textual scenario files to end with extension <b>.scenario</b>, by overriding the default behaviour of <a href="" which has no extension.</p> -<h2>Next?</h2> +<h2>What Next?</h2> <span class="followup">The <a href="" Scenarios</a> page will go into more configuration details and <a
Modified: trunk/core/distribution/src/site/content/getting-started.html (1261 => 1262)
--- trunk/core/distribution/src/site/content/getting-started.html 2009-09-19 20:53:52 UTC (rev 1261) +++ trunk/core/distribution/src/site/content/getting-started.html 2009-09-19 22:50:10 UTC (rev 1262) @@ -8,9 +8,11 @@ <h2>Getting Started</h2> +<h3>Write a textual scenario</h3> + <p>To start using JBehave, simply name your scenario file with underscores, eg i_can_toggle_a_cell (although the file name resolution -is configurable) and define steps in it: +is configurable) and define steps in it:</p> <pre class="brush: plain"> Given a 5 by 5 game When I toggle the cell at (2, 3) @@ -35,16 +37,14 @@ ..... ..X.. </pre> -A few more elements are required: -<p>1. Extend the <a + +<h3>Map textual scenario to Java class</h3> + +<p>Extend the <a href="" -class with a similarly named Java class: <code>ICanToggleACell.java</code> +class with a similarly named Java class: <b>ICanToggleACell.java</b> </p> -<p>2. Extend the <a - href="" -class - this is where your steps will be defined, and you can have as -many as you want. Associate the Steps with the Scenario: <pre class="brush: java"> public class ICanToggleACell extends Scenario { @@ -53,11 +53,17 @@ } } </pre> -</p> -<p>3. <a + +<h3>Map textual scenario steps to Java methods</h3> + +<p>Extend the <a + href="" +class: this is where your steps will be defined, and you can have as +many as you want. <a href="" methods in your step class to match the ones in your plain text -scenario. +scenario.</p> + <pre class="brush: java"> public class GridSteps extends Steps { @@ -82,10 +88,12 @@ } } - </pre> -</p> -<p>4. Run your new scenario as JUnit test.</p> +</pre> +<h3>Run Scenario</h3> + +<p>Run your new Java Scenario as JUnit test, in your favourite IDE.</p> + <h2>Looking for more examples?</h2> <span class="followup">JBehave has a number of working <a
Modified: trunk/core/distribution/src/site/content/license.html (1261 => 1262)
--- trunk/core/distribution/src/site/content/license.html 2009-09-19 20:53:52 UTC (rev 1261) +++ trunk/core/distribution/src/site/content/license.html 2009-09-19 22:50:10 UTC (rev 1262) @@ -6,14 +6,16 @@ </head> <body> + <h2>Overview</h2> + <p>Typically the licenses listed for the project are that of the project itself, and not of dependencies.</p> <h2>JBehave License</h2> -<p>JBehave is released under a BSD-style license: -<pre> +<p>JBehave is released under a BSD-style license:</p> +<pre class="brush: plain"> Copyright (c) 2003-2009 jbehave.org All rights reserved. @@ -40,6 +42,6 @@ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -</pre></p> +</pre> </body> </html>
Modified: trunk/core/distribution/src/site/content/parameter-converters.html (1261 => 1262)
--- trunk/core/distribution/src/site/content/parameter-converters.html 2009-09-19 20:53:52 UTC (rev 1261) +++ trunk/core/distribution/src/site/content/parameter-converters.html 2009-09-19 22:50:10 UTC (rev 1262) @@ -8,8 +8,124 @@ <h2>Parameter Converters</h2> -<p>JBehave allows you to define custom parameter converters for user domain types.</p> +<h3>Build-in support for Java types and Lists</h3> +<p>JBehave automatically converts the textual representation of a +parameter extracted from the candidate step with the parameter type of +the matched method in the Steps class. Let's go back to our example to +make this point clear. Consider a single textual step:</p> +<pre class="brush: plain"> + Given a stock of symbol STK1 and a threshold of 10.0 +</pre> +<p>which we map to the Java method:</p> +<pre class="brush: java"> + @Given("a stock of symbol $symbol and a threshold of $threshold") + public void aStock(String symbol, double threshold) { + // ... + } +</pre> +<p>The two arguments which are identified as parameters in matching +the textual step to the annotation pattern are: "STK1" and "1.0". These +are converted respectively to a <b>String</b> and a <b>double</b>.</p> +<p>If we had comma-separated values, e.g</p> +<pre class="brush: plain"> + Given a stock of symbols STK1,STK2 and thresholds of 10.0,20.0 +</pre> +<p>these would handled automatically as well, provided the type of +the parameter was a <a + href="" +<pre class="brush: java"> + @Given("a stock of symbols $symbols and thresholds $thresholds") + public void aStock(List<String> symbols, List<Double> thresholds) { + // ... + } +</pre> +<p>More in general, JBehave provides out-of-the-box support for +Strings, numbers and the lists thereof.</p> + +<h3>ParameterConverter interface</h3> + +<p>At the core of the parameter conversion mechanism lies the <a + href="" +facade and the interface: +<pre class="brush: java"> +public static interface ParameterConverter { + + boolean accept(Type type); + + Object convertValue(String value, Type type); + +} +</pre> +<p>The built-in support for Java types is provided by +implementations of this interface. Specifically:</p> +<ul> + <li>NumberConverter</li> + <li>NumberListConverter</li> + <li>StringListConverter</li> +</ul> + +<h3>Support for custom parameter converters</h3> + +<p>This mechanism then allows for custom converters to be defined +too. For example, let's consider the case of date conversion, a rather +common one. The step would typically look like:</p> +<pre class="brush: plain"> + When a stock of symbol STK1 is traded on 09/09/2009 +</pre> +<p>and the matching step is</p> +<pre class="brush: java"> + @When("a stock of symbol $symbol is traded on $tradedOn") + public void aStockIsTradedOn(String symbol, Date tradedOn) { + // ... + } +</pre> +<p>Out of the box, JBehave cannot know how to convert the argument +value <b>"09/09/2009"</b> to a Date object. Date formats are far from +standard. In this case, we want to use the date format </b>"dd/MM/yyyy"</b> and +configure the parameter converter for Date type. An implementation of +Date converter, backed up a <a + href="" +could be:</p> + +<pre class="brush: java"> +public class DateConverter implements ParameterConverter { + + private final SimpleDateFormat dateFormat; + + public DateConverter(String dateFormat) { + this.dateFormat = new SimpleDateFormat(dateFormat); + } + + public boolean accept(Type type) { + if (type instanceof Class<?>) { + return Date.class.isAssignableFrom((Class<?>) type); + } + return false; + } + + public Object convertValue(String value, Type type) { + try { + return dateFormat.parse(value); + } catch (ParseException e) { + throw new RuntimeException("Could not convert value "+value+" with format "+dateFormat.toPattern()); + } + } + +} +</pre> +<p>Then we configure the use of the newly defined <b>DateConverter</b> +in our Steps class:</p> +<pre class="brush: java"> + private static final StepsConfiguration configuration = new StepsConfiguration(); + + public MySteps(ClassLoader classLoader) { + super(configuration); + configuration.useParameterConverters(new ParameterConverters( + new DateConverter("dd/MM/yyyy))); // define converter for custom type Date + } + +</pre> <div class="clear"> <hr /> </div>
Modified: trunk/core/distribution/src/site/content/parameter-injection.html (1261 => 1262)
--- trunk/core/distribution/src/site/content/parameter-injection.html 2009-09-19 20:53:52 UTC (rev 1261) +++ trunk/core/distribution/src/site/content/parameter-injection.html 2009-09-19 22:50:10 UTC (rev 1262) @@ -8,8 +8,58 @@ <h2>Parameter Injection</h2> -<p>JBehave supports multiple mechanism for parameter injection.</p> +<p>JBehave supports multiple mechanisms for parameter injection.</p> +<h3>Ordered Parameters</h3> + +<p>This is the default behaviour. The arguments extracted from the +candidate step are simply matched following natural order to the +parameters in the annotated Java method. For example:</p> +<pre class="brush: plain"> + Given a stock of symbol STK1 and a threshold of 10.0 +</pre> +<p>Arguments "STK1" and "10.0" are matched to the first and second +method parameters of the Java method:</p> +<pre class="brush: java"> + @Given("a stock of symbol $symbol and a threshold of $threshold") + public void aStock(String symbol, double threshold) { + // ... + } +</pre> +<p>The names of the parameters (<b>symbol</b> and <b>threshold</b>) +are not actually relevant, and there is no need for them to match the +names of the argument capturers (<b>$symbol</b> and <b>$threshold</b>), +although it is good practice to keep them matching.</p> + +<h3>Annotated Named Parameters</h3> + +<p>If we want to have named parameters, one mechanism is to use annotations:</p> +<pre class="brush: java"> + @Given("a stock of symbol $symbol and a threshold of $threshold") + public void aStock(@Named("symbol") String aSymbol, @Named("threshold") double aThreshold) { + // ... + } +</pre> +<p>One reason to use named parameters is that then we can have method parameter appearing in any order:</p> +<pre class="brush: java"> + @Given("a stock of symbol $symbol and a threshold of $threshold") + public void aStock(@Named("threshold") double aThreshold, @Named("symbol") String aSymbol) { + // ... + } +</pre> +<p>Another use case of named parameters is the use of <a href="" examples</a>.</p> + +<h3>Paranamer Named Parameters</h3> + +<p>JBehave also supports an equivalent way to use named parameters, without using annotations, but leveraging +<a href="" configured via the <a + href="" + +<pre class="brush: java"> + Paranamer paranamer = new CachingParanamer(new BytecodeReadingParanamer()); + StepConfiguration configuration = new StepsConfiguration(); + configuration.useParanamer(paranamer); +</pre> <div class="clear"> <hr /> </div>
Modified: trunk/core/distribution/src/site/content/running-scenarios.html (1261 => 1262)
--- trunk/core/distribution/src/site/content/running-scenarios.html 2009-09-19 20:53:52 UTC (rev 1261) +++ trunk/core/distribution/src/site/content/running-scenarios.html 2009-09-19 22:50:10 UTC (rev 1262) @@ -20,24 +20,17 @@ <h2>Running as Ant task</h2> -<p> <pre class="brush: xml"> <taskdef name="scenarioRunner" classname="org.jbehave.ant.ScenarioRunnerTask" classpathref="your.runtime.classpath" /> - <scenarioRunner - scenarioClassNames="org.jbehave.examples.trader.scenarios.StatusAlertCanBeActivated,org.jbehave.examples.trader.scenarios.StatusAlertCanBeActivated" /> - - <scenarioRunner - scenarioIncludes="org/jbehave/examples/trader/scenarios/*.java" + <scenarioRunner scenarioIncludes="**/scenarios/*.java" scenarioExcludes="**/*Steps.java" /> </pre> -Remember that you need to include -<b>jbehave-ant</b> -to your runtime classpath. -</p> +<p>Remember that you need to include <b>jbehave-ant</b> to your +runtime classpath.</p> <h2>Running as Maven Plugin</h2> @@ -48,24 +41,11 @@ <version>[version]</version> <executions> <execution> - <id>run-scenarios-listed</id> - <phase>integration-test</phase> - <configuration> - <scenarioClassNames> - <scenarioClassName>org.jbehave.examples.trader.scenarios.StatusAlertCanBeActivated</scenarioClassName> - <scenarioClassName>org.jbehave.examples.trader.scenarios.StatusAlertIsNeverActivated</scenarioClassName> - </scenarioClassNames> - </configuration> - <goals> - <goal>run-scenarios</goal> - </goals> - </execution> - <execution> <id>run-scenarios-found</id> <phase>integration-test</phase> <configuration> <scenarioIncludes> - <scenarioInclude>org/jbehave/examples/trader/scenarios/*.java</scenarioInclude> + <scenarioInclude>**/scenarios/*.java</scenarioInclude> </scenarioIncludes> <scenarioExcludes> <scenarioExclude>**/*Steps.java</scenarioExclude> @@ -78,8 +58,8 @@ </executions> </plugin> </pre> -</p> + <div class="clear"> <hr /> </div>
Modified: trunk/core/distribution/src/site/content/sitemap.xml (1261 => 1262)
--- trunk/core/distribution/src/site/content/sitemap.xml 2009-09-19 20:53:52 UTC (rev 1261) +++ trunk/core/distribution/src/site/content/sitemap.xml 2009-09-19 22:50:10 UTC (rev 1262) @@ -22,9 +22,10 @@ <page>i18n.html</page> </section> <section> - <name>Step Parameters</name> + <name>Advanced Topics</name> <page>parameter-injection.html</page> <page>parameter-converters.html</page> + <page>table-examples.html</page> </section> <section> <name>Project Info</name>
Modified: trunk/core/distribution/src/site/content/source-repository.html (1261 => 1262)
--- trunk/core/distribution/src/site/content/source-repository.html 2009-09-19 20:53:52 UTC (rev 1261) +++ trunk/core/distribution/src/site/content/source-repository.html 2009-09-19 22:50:10 UTC (rev 1262) @@ -2,50 +2,59 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> - <title>Source Repository</title> +<title>Source Repository</title> </head> <body> - <h2>Overview</h2> -<p>This project uses a Source Content Management System to manage its source code.</p><h2>Web Access</h2> +<p>This project uses a Source Content Management System to manage +its source code.</p> -<p>The following is a link to the online source repository.</p> +<h2>Web Access</h2> - <pre><a href="" +<p>The following is a link to the online source repository:</p> +<p><a href="" + <h2>Developer access</h2> -<p>Everyone can access the Subversion repository via HTTPS, but Committers must checkout the Subversion repository via - HTTPS.</p> +<p>Everyone can access the Subversion repository via HTTPS, but +Committers must checkout the Subversion repository via HTTPS.</p> - <pre>$ svn checkout https://svn.codehaus.org/jbehave/trunk jbehave</pre> -<p>To commit changes to the repository, execute the following command to commit your changes (svn will prompt you for - your password)</p> +<pre>$ svn checkout https://svn.codehaus.org/jbehave/trunk/core jbehave</pre> +<p>To commit changes to the repository, execute the following +command to commit your changes (svn will prompt you for your password)</p> - <pre>$ svn commit --username your-username -m "A message"</pre> +<pre>$ svn commit --username your-username -m "A message"</pre> <h2>Access from behind a firewall</h2> -<p>For those users who are stuck behind a corporate firewall which is blocking http access to the Subversion repository, - you can try to access it via the developer connection:</p> +<p>For those users who are stuck behind a corporate firewall which +is blocking http access to the Subversion repository, you can try to +access it via the developer connection:</p> - <pre>$ svn checkout https://svn.codehaus.org/jbehave/trunk jbehave</pre> +<pre>$ svn checkout https://svn.codehaus.org/jbehave/trunk jbehave</pre> <h2>Access through a proxy</h2> -<p>The Subversion client can go through a proxy, if you configure it to do so. First, edit your "servers" - configuration file to indicate which proxy to use. The files location depends on your operating system. On Linux or - Unix it is located in the directory "~/.subversion". On Windows it is in "%APPDATA%\Subversion". - (Try "echo %APPDATA%", note this is a hidden directory.)</p> +<p>The Subversion client can go through a proxy, if you configure it +to do so. First, edit your "servers" configuration file to +indicate which proxy to use. The files location depends on your +operating system. On Linux or Unix it is located in the directory +"~/.subversion". On Windows it is in +"%APPDATA%\Subversion". (Try "echo %APPDATA%", note +this is a hidden directory.)</p> -<p>There are comments in the file explaining what to do. If you don't have that file, get the latest Subversion client - and run any command; this will cause the configuration directory and template files to be created.</p> +<p>There are comments in the file explaining what to do. If you +don't have that file, get the latest Subversion client and run any +command; this will cause the configuration directory and template files +to be created.</p> -<p>Example : Edit the 'servers' file and add something like :</p> +<p>Example: Edit the 'servers' file and add something like :</p> -<pre>[global] +<pre class="brush: plain"> +[global] http-proxy-host = your.proxy.name http-proxy-port = 3128 </pre>
Added: trunk/core/distribution/src/site/content/table-examples.html (0 => 1262)
--- trunk/core/distribution/src/site/content/table-examples.html (rev 0) +++ trunk/core/distribution/src/site/content/table-examples.html 2009-09-19 22:50:10 UTC (rev 1262) @@ -0,0 +1,52 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html> +<head> +<title>Table Examples</title> +</head> + +<body> + +<h2>Table Examples</h2> + +<p>Scenario writer often find themselves repeating scenarios, or +parts thereof, by simply changing some parameter values. These are ideal +candidates for using JBehave Table Examples feature. Let's look at the +example:</p> + +<pre class="brush: plain"> + Given a stock of symbol STK1 and a threshold of 10.0 + When the stock is traded at 5.0 + Then the alert status should be OFF + When the stock is traded at 11.0 + Then the alert status should be ON +</pre> + +<p>We notice that two lines are repeated and identical but for the +values. We can then rewrite this scenario as:</p> + +<pre class="brush: plain"> + Given a stock of symbol [symbol] and a threshold of [threshold] + When the stock is traded at [price] + Then the alert status should be [status] + + Examples: + + |symbol|threshold|price|status| + |STK1|10.0|5.0|OFF| + |STK1|10.0|11.0|ON| +</pre> +<p>The <b>Examples:</b> keyword signals that the scenario should be +repeated for as many times as there are data rows in the examples table. +At each execution, the named parameters are taken from the corresponding +row.</p> + +<p>Note that use of table examples requires more <a + href="" named parameters</a> for the +candidate steps to be matched to Java methods.</p> + +<div class="clear"> +<hr /> +</div> + +</body> +</html> \ No newline at end of file
Added: trunk/core/examples/trader/src/main/java/org/jbehave/examples/trader/converters/DateConverter.java (0 => 1262)
--- trunk/core/examples/trader/src/main/java/org/jbehave/examples/trader/converters/DateConverter.java (rev 0) +++ trunk/core/examples/trader/src/main/java/org/jbehave/examples/trader/converters/DateConverter.java 2009-09-19 22:50:10 UTC (rev 1262) @@ -0,0 +1,33 @@ +package org.jbehave.examples.trader.converters; + +import java.lang.reflect.Type; +import java.text.ParseException; +import java.text.SimpleDateFormat; +import java.util.Date; + +import org.jbehave.scenario.steps.ParameterConverters.ParameterConverter; + +public class DateConverter implements ParameterConverter { + + private final SimpleDateFormat dateFormat; + + public DateConverter(String dateFormat) { + this.dateFormat = new SimpleDateFormat(dateFormat); + } + + public boolean accept(Type type) { + if (type instanceof Class<?>) { + return Date.class.isAssignableFrom((Class<?>) type); + } + return false; + } + + public Object convertValue(String value, Type type) { + try { + return dateFormat.parse(value); + } catch (ParseException e) { + throw new RuntimeException("Could not convert value "+value+" with format "+dateFormat.toPattern()); + } + } + +}
To unsubscribe from this list please visit:
