- Revision
- 1372
- Author
- mauro
- Date
- 2009-10-31 11:08:33 -0500 (Sat, 31 Oct 2009)
Log Message
JBEHAVE-197: Improved documentation on candidate steps, aliases and annotations.
Modified Paths
- trunk/core/distribution/src/site/content/developing-scenarios.html
- trunk/core/distribution/src/site/content/sitemap.xml
Added Paths
Diff
Added: trunk/core/distribution/src/site/content/aliases.html (0 => 1372)
--- trunk/core/distribution/src/site/content/aliases.html (rev 0) +++ trunk/core/distribution/src/site/content/aliases.html 2009-10-31 16:08:33 UTC (rev 1372) @@ -0,0 +1,81 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html> +<head> +<title>Aliases</title> +</head> + +<body> + +<h2>Aliases</h2> + +<p><a href="" Development</a> +emphasises the importance of language in communication the behaviour of +the system from a business perspective. As such, the language used in +the textual scenarios is subject to change, evolving with the +understanding or the definition of the system itself.</p> + +<p>It is quite common therefore to want to express the same +underlying step functionality in slightly different ways, or to support +multiple syntaxes.</p> + +<p>JBehave addresses this use cases with <b>aliases</b>. For +example, let's consider the following step:</p> + +<pre class="brush: java"> + @When("the item price is $price") + public void theItemPriceIs(double price) { + // ... + } +</pre> + +<p>which matches the following textual step:</p> + +<pre class="brush: bdd"> +When the item price is 10.0 +</pre> + +<p>At some point in the evolution of the description of the +behaviour of the system, it may become necessary to underline the +evolving nature of the item price, i.e. that the price changes and +assumes a different value. In this case, it may be a more appropriate +description to use the verb <b>becomes</b> in place of <b>is</b>:</p> + +<pre class="brush: bdd"> +When the item price becomes 10.0 +</pre> + +<p>We can then add an <a + href="" +annotation with the new matching step pattern:</p> +<pre class="brush: java"> + @When("the item price is $price") + @Alias("the item price becomes $price") // single alias + public void theItemPriceIs(double price) { + // ... + } +</pre> + +<p>JBehave will then create for this method <b>two</b> <a + href="" steps</a>, both of type <b>WHEN</b>, +one for each of the two regex patterns, <b>"the item price is +$price"</b> and <b>"the item price becomes $price"</b>.</p> + +<p>An obvious generalisation of this concept is the support for +multiple aliases, via the <a + href="" +annotation:</p> +<pre class="brush: java"> + @When("the item price is $price") + @Aliases(values={"the item price becomes $price" + "the item price equals to $price"}) // multiple aliases + public void theItemPriceIs(double price) { + // ... + } +</pre> + +<div class="clear"> +<hr /> +</div> + +</body> +</html>
Added: trunk/core/distribution/src/site/content/annotations.html (0 => 1372)
--- trunk/core/distribution/src/site/content/annotations.html (rev 0) +++ trunk/core/distribution/src/site/content/annotations.html 2009-10-31 16:08:33 UTC (rev 1372) @@ -0,0 +1,104 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html> +<head> +<title>Annotations</title> +</head> + +<body> + +<h2>Step Annotations</h2> + +<p>JBehave supports the following Java method step annotations:</p> + +<ul> + <li><a + href="" + </li> + <li><a + href="" + </li> + <li><a + href="" + </li> + <li><a + href="" + </li> + <li><a + href="" + </li> +</ul> +<p>Each annotation holds a regex pattern as value, which is used to +match the <a href="" steps</a> to the +textual step:</p> + +<pre class="brush: java"> + @Given("a stock of symbol $symbol and a threshold of $threshold") + public void aStock(String symbol, double threshold) { + // ... + } + + @When("the stock is traded at $price") + @Alias("the stock is exchanged at $price") // single alias + public void theStockIsTradedAt(double price) { + // ... + } + + @Then("the alert status should be $status") + @Aliases(values={"the trader should be alerted of status $status", + "the alert status is at $status"}) // multiple aliases + public void theAlertStatusShouldBe(String status) { + // ... + } +</pre> + +<p>The use of <a href="" is optional.</p> + +<h2>Scenario Annotations</h2> + +<p>JBehave also supports the following Java method scenario +annotations:</p> + +<ul> + <li><a + href="" + </li> + <li><a + href="" + </li> +</ul> +<p>The <b>BeforeScenario</b> annotation holds no value and it allows +the corresponding method to be executed before each scenario, while the +<b>AfterScenario</b> holds an optional <a + href="" +value, which specifies whether the method should be executed depending on the +outcome of the scenario:</p> + +<pre class="brush: java"> + + @BeforeScenario + public void beforeEachScenario() { + // ... + } + + @AfterScenario // equivalent to @AfterScenario(uponOutcome=AfterScenario.Outcome.ANY) + public void afterAnyScenario() { + // ... + } + + @AfterScenario(uponOutcome=AfterScenario.Outcome.SUCCESS) + public void afterSuccessfulScenario() { + // ... + } + + @AfterScenario(uponOutcome=AfterScenario.Outcome.FAILURE) + public void afterFailedScenario() { + // ... + } +</pre> + +<div class="clear"> +<hr /> +</div> + +</body> +</html>
Added: trunk/core/distribution/src/site/content/candidate-steps.html (0 => 1372)
--- trunk/core/distribution/src/site/content/candidate-steps.html (rev 0) +++ trunk/core/distribution/src/site/content/candidate-steps.html 2009-10-31 16:08:33 UTC (rev 1372) @@ -0,0 +1,92 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html> +<head> +<title>Candidate Steps</title> +</head> + +<body> + +<h2>Candidate Steps</h2> + +<p>JBehave uses <a href="" in the <a + href="" +instance to associate an executable Java method to a <a + href="" +Each candidate step corresponds to one Java method and to one <a + href="" +A candidate step holds the regex pattern contained in the annotation value, which +is used to do the matching with the textual steps in the scenario.</p> +<p>Let's look at a concrete example:</p> +<pre class="brush: java"> +public class TraderSteps extends Steps { + + private Stock stock; + + @Given("a stock of symbol $symbol and a threshold of $threshold") + public void aStock(String symbol, double threshold) { + stock = new Stock(symbol, threshold); + } + + @When("the stock is traded at $price") + @Alias("the stock is sold at $price") + public void theStockIsTradedAt(double price) { + stock.tradeAt(price); + } + + @Then("the alert status should be $status") + public void theAlertStatusShouldBe(String status) { + ensureThat(stock.getStatus().name(), equalTo(status)); + } + +} +</pre> +<p>For each method annotated with one of the <a + href="" annotations</a>, a candidate step is +created. Note that each method can supports <a href="" +and a different candidate step is created for each alias.</p> + +<p>So, given one or more instances of Steps classes, each containing +a number of annotated methods, JBehave collects a list of candidate +steps, which are then used to match the textual steps found in the +scenarios being run. For each given <a + href="" +<b>the regex pattern must be unique</b>.</p> + +<p>Hence, the following two methods are allowed to have the same +regex pattern, because they correspond to different step types:</p> + +<pre class="brush: java"> + + @Given("a stock is traded at $price") + public void aStockWithPrice(double price) { + // ... + } + + @When("the stock is traded at $price") + public void theStockIsTradedAt(double price) { + // ... + } +</pre> + +<p>While the following would result in a runtime failure when +running the scenario:</p> + +<pre class="brush: java"> + + @When("a stock is traded at $price") + public void aStockWithPrice(double price) { + // ... + } + + @When("the stock is traded at $price") + public void theStockIsTradedAt(double price) { + // ... + } +</pre> + +<div class="clear"> +<hr /> +</div> + +</body> +</html>
Modified: trunk/core/distribution/src/site/content/developing-scenarios.html (1371 => 1372)
--- trunk/core/distribution/src/site/content/developing-scenarios.html 2009-10-31 14:45:30 UTC (rev 1371) +++ trunk/core/distribution/src/site/content/developing-scenarios.html 2009-10-31 16:08:33 UTC (rev 1372) @@ -8,8 +8,8 @@ <h2>Writing Textual Scenarios</h2> -<p>encourages you to start defining the scenarios that express -the desired behaviour in a textual format, e.g.:</p> +<p><a href="" Development</a> encourages you to start defining the scenarios that +express the desired behaviour in a textual format, e.g.:</p> <pre class="brush: bdd"> Given a stock of symbol STK1 and a threshold of 10.0 When the stock is traded at 5.0 @@ -25,16 +25,17 @@ <p>The scenario should use a syntax compatible with the <a href="" -<h2>Mapping Textual Scenario Steps to Java Methods</h2> +<h2>Mapping Textual Scenario Steps to Java Methods via annotations</h2> <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:</p> +instance. The scenario writer need only extend the default +implementation <a + href="" +and provide annotated methods that match, by regex patterns, the textual +steps:</p> <pre class="brush: java"> - public class TraderSteps extends Steps { +public class TraderSteps extends Steps { private Stock stock; @@ -55,14 +56,11 @@ } </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 +<p>Each step is annotated with one of the <a href="" +annotations</a>, 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 @@ -92,7 +90,7 @@ <p>Thus in our case the example Scenario would look like:</p> <pre class="brush: java"> - public class TraderIsAletedOfStatus extends JUnitScenario { +public class TraderIsAletedOfStatus extends JUnitScenario { public TraderIsAletedOfStatus() { this(Thread.currentThread().getContextClassLoader()); @@ -120,7 +118,9 @@ <span class="followup">The <a href="" Scenarios</a> page will go into more configuration details and <a href="" Scenarios</a> into the -different ways to run scenarios.</span> +different ways to run scenarios. Or if you want to learn more about +JBehave's step matching mechanism, you'll want to explored the concept +of <a href="" steps</a> in more detail. </span> <div class="clear"> <hr />
Modified: trunk/core/distribution/src/site/content/sitemap.xml (1371 => 1372)
--- trunk/core/distribution/src/site/content/sitemap.xml 2009-10-31 14:45:30 UTC (rev 1371) +++ trunk/core/distribution/src/site/content/sitemap.xml 2009-10-31 16:08:33 UTC (rev 1372) @@ -19,13 +19,16 @@ <section> <name>Scenarios</name> <page>developing-scenarios.html</page> + <page>annotations.html</page> + <page>candidate-steps.html</page> + <page>pending-steps.html</page> <page>configuring-scenarios.html</page> <page>running-scenarios.html</page> <page>i18n-scenarios.html</page> - <page>pending-steps.html</page> </section> <section> <name>Advanced Topics</name> + <page>aliases.html</page> <page>parameter-injection.html</page> <page>parameter-converters.html</page> <page>table-examples.html</page>
To unsubscribe from this list please visit:
