buildr 1.3.0-java

data/doc/pages/settings_profiles.textile

@@ -0,0 +1,339 @@
+h1. Settings/Profiles
+
+
+h2.  Environment Variables
+
+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).
+
+For example:
+
+{{{!sh
+$ export HTTP_PROXY=http://myproxy:8080
+}}}
+
+There are other environment variables you will want to set when running Buildr,
+for example, to do a full build without running the tests:
+
+{{{!sh
+$ buildr test=no
+}}}
+
+For convenience, when you set environment variables on the command line, the
+variable name is case insensitive, you can use either @test=no@ or @TEST=no@.
+Any other way (@export@, @ENV@, etc) the variable names are case sensitive.
+
+You can also set environment variables from within your Buildfile.  For
+example, if you discover that building your project requires gobs of JVM heap
+space, and you want all other team members to run with the same settings:
+
+{{{!ruby
+# This project builds a lot of code.
+ENV['JAVA_OPTS'] ||= '-Xms1g -Xmx1g'
+}}}
+
+Make sure to set any environment variables at the very top of the Buildfile,
+above any Ruby statement (even @require@).
+
+p(tip).  Using @||=@ 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.
+
+Buildr supports the following environment variables:
+
+|_. Variable    |_. Description |
+| @BUILDR_ENV@  | Environment name (development, production, test, etc).
+Another way to set this is using the @-e@ command line option. |
+| @DEBUG@       | Set to @no/off@ if you want Buildr to compile without
+debugging information (default when running the @release@ task, see
+"Compiling":building.html#compiling). |
+| @HOME@        | Your home directory. |
+| @HTTP_PROXY@  | URL for HTTP proxy server (see "Specifying
+Repositories":artifacts.html#specifying_repositories). |
+| @JAVA_HOME@   | Points to your JDK, required when using Java and Ant. |
+| @JAVA_OPTS@   | Command line options to pass to the JDK (e.g. @'-Xms1g'@). |
+| @M2_REPO@     | Location of the Maven2 local repository.  Defaults to the
+@.m2@ directory in your home directory (@ENV['HOME']@). |
+| @NO_PROXY@    | Comma separated list of hosts and domain that should not be
+proxied (see "Specifying Repositories":artifacts.html#specifying_repositories).  |
+| @TEST@        | Set to @no/off@ to tell Buildr to skip tests, or @all@ to
+tell Buildr to run all tests and ignore failures (see "Running
+Tests":testing.html#running_tests). |
+| @USER@        | Tasks that need your user name, for example to log to remote
+servers, will use this environment variable. |
+
+p(note). Buildr does not check any of the arguments in @JAVA_OPTS@.  A common
+mistake is to pass an option like @mx512mb@, where it should be @Xmx512mb@.
+Make sure to double check @JAVA_OPTS@.
+
+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:
+
+{{{!ruby
+repositories.upload_to[:username] = ENV['USERNAME']
+repositories.upload_to[:password] = ENV['PASSWORD']
+}}}
+
+
+h2. Personal Settings
+
+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.
+
+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.
+
+The prefered way to store personal settings is to create a @.buildr/settings.yaml@
+file under your home directory. Settings stored there will be applied the same
+across all builds.
+
+Here's an example @settings.yaml@:
+
+{{{!yaml
+# The repositories hash is read automatically by buildr.
+repositories:
+
+  # customize user local maven2 repository location
+  local: some/path/to/my_repo
+
+  # prefer the local or nearest mirrors
+  remote: 
+   - https://intra.net/maven2
+   - http://example.com
+
+  relase_to:
+    url: http://intra.net/maven2
+    username: john
+    password: secret
+
+# You can place settings of your own, and reference them 
+# on buildfiles. 
+im:
+  server: jabber.company.com
+  usr: notifier@company-jabber.com
+  pwd: secret
+}}}
+
+Later your buildfile or addons can reference user preferences using the 
+hash returned by the @Buildr.settings.user@ accessor.
+
+{{{!ruby
+task 'relase-notification' do
+ usr, pwd, server = settings.user['im'].values_at('usr', 'pwd', 'server')
+ jabber = JabberAPI.new(server, usr, pwd)
+ jabber.msg("We are pleased to announce the last stable version #{VERSION}")
+end
+}}}
+
+
+h2. Build Settings
+
+Build settings are local to the project being built, and are placed in the
+@build.yaml@ file located in the same directory that the @buildfile@. Normally
+this file would be managed by the project revision control system, so settings
+here are shared between developers.
+
+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.
+
+{{{!yaml
+# This project requires the following ruby gems, buildr addons
+gems: 
+  # Suppose we want to notify developers when testcases fail.
+  - buildr-twitter-notifier-addon >=1
+  # we test with ruby mock objects
+  - mocha
+  - ci_reporter
+
+# The artifact declarations will be automatically loaded by buildr, so that
+# you can reference artifacts by name (a ruby-symbol) on your buildfile.
+artifacts:
+  spring: org.springframework:spring:jar:2.0
+  log4j: log4j:log4j:jar:1.0
+  j2ee: geronimo-spec:geronimo-spec-j2ee:jar:1.4-rc4
+
+# Of course project settings can be defined here
+twitter:
+  notify:
+    test_failure: unless-modified
+    compile_failure: never
+  developers: 
+    - joe
+    - jane
+
+jira: 
+  uri: https://jira.corp.org
+}}}
+
+When buildr is loaded, required ruby gems will be installed if needed, thus adding
+features like the imaginary twitter notifier addon.
+
+Artifacts defined on @build.yaml@ can be referenced on your buildfile by supplying
+the ruby symbol to the @Buildr.artifact@ and @Buildr.artifacts@ methods. 
+The @compile.with@, @test.with@ methods can also be given these names.
+
+{{{!ruby
+define 'my_project' do 
+  compile.with artifacts(:log4j, :j2ee)
+  test.with :spring, :j2ee
+end
+}}}
+
+Build settings can be retreived using the @Buildr.settings.build@ accessor.
+
+{{{!ruby
+ task 'create_patch' do 
+   patch = Git.create_patch :interactive => true
+   if patch && agree("Would you like to request inclusion of #{patch}")
+     jira = Jira.new( Buildr.settings.build['jira']['uri'] )  # submit a patch
+     jira.create(:improvement, patch.summary, :attachment => patch.blob)
+   end
+ end
+}}}
+
+h2. Non constant settings
+
+Before loading the Buildfile, Buildr will attempt to load two other files: the
+@buildr.rb@ file it finds in your home directory, followed by the @buildr.rb@
+file it finds in the build directory.
+
+The loading order allows you to place global settings that affect all your
+builds in your home directory's @buildr.rb@, but also over-ride those with
+settings for a given project.
+
+Here's an example @buildr.rb@:
+
+{{{!ruby
+# Only I should know that
+repositories.upload_to[:username] = 'assaf'
+repositories.upload_to[:password] = 'supersecret'
+# Search here first, it's faster
+repositories.remote << 'http://inside-the-firewall'
+}}} 
+
+
+h2. Environments
+
+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.
+
+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
+@environment@ method.  You can set the current build environment in one of two
+ways.  Using the @-e/--environment@ command line option:
+
+{{{!sh
+$ buildr -e test
+(in /home/john/project, test)
+}}}
+
+Or by setting the environment variable @BUILDR_ENV@:
+
+{{{!
+$ export BUILDR_ENV=production
+$ buildr
+(in /home/john/project, production)
+}}}
+
+Unless you tell it otherwise, Buildr assumes you're developing and sets the
+environment to @development@.
+
+Here's a simple example for handling different environments within the
+Buildfile:
+
+{{{!ruby
+project 'db-module' do
+  db = (environment == 'production' ? 'oracle' : 'hsql')
+  resources.from(_(:source, :main, db))
+end
+}}}
+
+We recommend picking a convention for your different environments and following
+it across all your projects.  For example:
+
+|_. Environment |_. Use when ... |
+| development   | Developing on your machine. |
+| test          | Running in test environment, continuous integration. |
+| production    | Building for release/production. |
+
+
+h2.  Profiles
+
+Different environments may require different configurations, some you will want
+to control with code, others you will want to specify in the profiles file.
+
+The profiles file is a YAML file called @profiles.yaml@ that you place in the
+same directory as the Buildfile.  We selected YAML because it's easier to read
+and edit than XML.
+
+For example, to support three different database configurations, we could write:
+
+{{{!yaml
+# HSQL, don't bother storing to disk.
+development:
+  db: hsql
+  jdbc: hsqldb:mem:devdb
+
+# Make sure we're not messing with bigstrong.
+test:
+  db: oracle
+  jdbc: oracle:thin:@localhost:1521:test
+
+# The real deal.
+production:
+  db: oracle
+  jdbc: oracle:thin:@bigstrong:1521:mighty
+}}}
+
+Here's a simple example for a buildfile that uses the profile information:
+
+{{{!ruby
+project 'db-module' do
+  # Copy SQL files specific for the database we're using,
+  # for example, everything under src/main/hsql.
+  resources.from(_(:source, :main, profile['db']))
+  # Set the JDBC URL in copied resource files (config.xml needs this).
+  resources.filter :jdbc=>profile['jdbc']
+end
+}}}
+
+The @profile@ method returns the current profile, selected based on the current
+"environment":#environments.  You can get a list of all profiles by calling
+@profiles@.
+
+When you run the above example in @development@, the current profile will
+return the hash @{ 'db'=>'hsql', 'jdbc'=>'hsqldb:mem:devdb' }@.
+
+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 DRY.
+
+YAML allows you to use anchors (@&@), similar to ID attributes in XML,
+reference the anchored element (@*@) elsewhere, and merge one element into
+another (@<<@).  For example:
+
+
+{{{!yaml
+# We'll reference this one as common.
+development: &common
+  db: hsql
+  jdbc: hsqldb:mem:devdb
+  resources:
+    copyright: Me (C) 2008
+# Merge the values from common, override JDBC URL.
+test:
+  <<: *common
+  jdbc: hsqldb:file:testdb
+}}}
+
+You can "learn more about YAML here":http://www.yaml.org, and use this
+handy "YAML quick reference":http://www.yaml.org/refcard.html.

data/doc/pages/testing.textile

@@ -0,0 +1,475 @@
+h1. Testing
+
+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.
+
+
+h2. Writing Tests
+
+Each project has a @TestTask@ that you can access using the @test@ method.
+@TestTask@ reflects on the fact that each project has one task responsible for
+getting the tests to run and acting on the results.  But in fact there are
+several tasks that do all the work, and a @test@ task coordinates all of that.
+
+The first two tasks to execute are @test.compile@ and @test.resources@.  They
+work similar to @compile@ and @resources@, but uses a different set of
+directories.  For example, Java tests compile from the @src/test/java@
+directory into the @target/test/classes@ directory, while resources are copied
+from @src/test/resources@ into @target/test/resources@.
+
+The @test.compile@ task will run the @compile@ task first, then use the same
+dependencies to compile the test classes.  That much you already assumed.  It
+also adds the test framework (e.g. JUnit, TestNG) and JMock to the dependency
+list.  Less work for you.
+
+If you need more dependencies, the best way to add them is by calling
+@test.with@.  This method adds dependencies to both @compile.dependencies@ (for
+compiling) and @test.dependencies@ (for running).  You can manage these two
+dependency lists separately, but using @test.with@ is good enough in more
+cases.
+
+Once compiled, the @test@ task runs all the tests.
+
+
+h2. Using JUnit
+
+The default test framework for Java projects is JUnit 4.
+
+When you use JUnit, the dependencies includes JUnit, and Buildr picks up all
+test classes from the project by looking for classes that either subclass 
+@junit.framework.TestCase@, include methods annotated with @org.junit.Test@,
+or test suites annotated with @org.org.junit.runner.RunWith@.
+
+The JUnit test framework supports the following options:
+
+|_. Option        |_. Value |
+| @:fork@         | VM forking, defaults to true. |
+| @:clonevm@      | If true clone the VM each time it is forked. |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:environment@  | Hash of environment variables available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. |
+
+For example, to pass properties to the test case:
+
+{{{!ruby
+test.using :properties=>{ :currency=>'USD' }
+}}}
+
+There are benefits to running test cases in separate VMs.  The default forking
+mode is @:once@, and you can change it by setting the @:fork@ option.
+
+|_. :fork=> |_. Behavior |
+| @:once@   | Create one VM to run all test classes in the project, separate
+VMs for each project. |
+| @:each@   | Create one VM for each test case class.  Slow but provides the
+best isolation between test classes. |
+| @false@   | Without forking, Buildr runs all test cases in a single VM.  This
+option runs fastest, but at the risk of running out of memory and causing test
+cases to interfere with each other. |
+
+You can see your tests running in the console, and if any tests fail, Buildr
+will show a list of the failed test classes.  In addition, JUnit produces text
+and XML report files in the project's @reports/junit@ directory.  You can use
+that to get around too-much-stuff-in-my-console, or when using an automated
+test system.
+
+In addition, you can get a consolidated XML or HTML report by running the
+@junit:report@ task.  For example:
+
+{{{!sh
+$ buildr test junit:report test=all
+$ firefox report/junit/html/index.html
+}}}
+
+The @junit:report@ task generates a report from all tests run so far.  If you
+run tests in a couple of projects, it will generate a report only for these two
+projects.  The example above runs tests in all the projects before generating
+the reports.
+
+
+h2. Using TestNG
+
+You can also use TestNG in your project by telling your project to use TestNG:
+
+{{{!ruby
+test.using :testng
+}}}
+
+Like all other options you can set with @test.using@, it affects the projects
+and all its sub-projects, so you only need to do this once at the top-most
+project to use TestNG throughout.  You can also mix TestNG and JUnit by setting
+different projects to use different frameworks, but you can't mix both
+frameworks in the same project.  (And yes, @test.using :junit@ will switch a
+project back to using JUnit)
+
+TestNG works much like JUnit, it gets included in the dependency list, Buildr
+picks test classes that contain methods annotated with 
+@org.testng.annotations.Test@, and generates test reports in
+the @reports/testng@ directory.  At the moment we don't have consolidated HTML
+reports for TestNG.
+
+The TestNG test framework supports the following options:
+
+|_. Option        |_. Value |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. |
+
+
+h2. Excluding Tests and Ignoring Failures
+
+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:
+
+{{{!ruby
+test.include 'com.acme.tests.passing.*'
+}}}
+
+Or tell it to exclude specific tests, for example:
+
+{{{!ruby
+test.exclude '*FailingTest', '*FailingWorseTest'
+}}}
+
+Note that we're always using the package qualified class name, and you can use
+star (@*@) to substitute for any set of characters.
+
+When tests fail, Buildr fails the @test@ task.  This is usually a good thing,
+but you can also tell Buildr to ignore failures by resetting the
+@:fail_on_failure@ option:
+
+{{{!ruby
+test.using :fail_on_failure=>false
+}}}
+
+Besides giving you a free pass to ignore failures, you can use it for other
+causes, for example, to be somewhat forgiving:
+
+{{{!ruby
+test do
+  fail 'More than 3 tests failed!' if test.failed_tests.size > 3
+end
+}}}
+
+The @failed_tests@ collection holds the names of all classes with failed tests.
+And there's @classes@, which holds the names of all test classes.  Ruby
+arithmetic allows you to get the name of all passed test classes with a simple
+@test.classes – test.failed_tests@.  We'll let you imagine creative use for
+these two.
+
+
+h2. Running Tests
+
+It's a good idea to run tests every time you change the source code, so we
+wired the @build@ task to run the @test@ task at the end of the build.  And
+conveniently enough, the @build@ task is the default task, so another way to
+build changes in your code and run your tests:
+
+{{{!sh
+$ buildr
+}}}
+
+That only works with the local @build@ task and any local task that depends on
+it, like @package@, @install@ and @upload@.  Each project also has its own
+@build@ task that does not invoke the @test@ task, so @buildr build@ will run
+the tests cases, but @buildr foo:build@ will not.
+
+While it's a good idea to always run your tests, it's not always possible.
+There are two ways you can get @build@ to not run the @test@ task.  You can set
+the environment variable @test@ to @no@ (but @skip@ and @off@ will also work).
+You can do that when running Buildr:
+
+{{{!sh
+$ buildr test=no
+}}}
+
+Or set it once in your environment:
+
+{{{!sh
+$ export TEST=no
+$ buildr
+}}}
+
+If you're feeling really adventurous, you can also disable tests from your
+Buildfile or @buildr.rb@ file, by setting @options.test = false@. We didn't say
+it's a good idea, we're just giving you the option.
+
+The @test@ 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 @test@ task with a pattern.  For example:
+
+{{{!sh
+$ buildr test:KillerAppTest
+}}}
+
+Buildr will then run only tests that match the pattern @KillerAppTest@.  It
+uses pattern matching, so @test:Foo@ will run @com.acme.FooTest@ and
+@com.acme.FooBarTest@.  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:
+
+{{{!sh
+$ buildr test:FooTest,BarTest
+}}}
+
+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 @test@ to "all", or the Buildr @options.test@ option to @:all@.  For
+example:
+
+{{{!sh
+$ buildr package test=all
+}}}
+
+We're using @package@ and not @build@ 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.
+
+
+h2. Integration Tests
+
+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 @build@ task, and include JMock in the dependency list.
+
+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.
+
+You write integration tests much the same way as you write unit tests, using
+@test.compile@ and @test.resources@.  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:
+
+{{{!ruby
+test.using :integration
+}}}
+
+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 @:integration@ option with the later.
+
+To run integration tests on the current project:
+
+{{{!sh
+$ buildr integration
+}}}
+
+You can also run specific tests cases, for example:
+
+{{{!sh
+$ buildr integration:ClientTest
+}}}
+
+If you run the @package@ task (or any task that depends on it, like @install@
+and @upload@), Buildr will first run the @build@ 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 @test@ to "no" to skip integration
+tests, or "all" to ignore failures.
+
+
+h2. Using Setup and Teardown
+
+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.
+
+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 @integration.setup@ and @integration.teardown@.  For
+example:
+
+{{{!ruby
+integration.setup { server.start ; server.deploy }
+integration.teardown { server.stop }
+}}}
+
+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.
+
+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
+@test.setup@ and @test.teardown@.
+
+
+h2. Testing Your Build
+
+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 CSS 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?
+
+Each project has a @check@ task that runs just after packaging.  You can use
+this task to verify that your build created the files you wanted it to create.
+And to make it extremely convenient, we introduced the notion of expectations.
+
+You use the @check@ method to express and expectation.  Buildr will then run
+all these expectations against your project, and fail at the first expectation
+that doesn't match.  An expectation says three things.  Let's look at a few
+examples:
+
+{{{!ruby
+check package(:war), 'should exist' do
+  it.should exist
+end
+check package(:war), 'should contain a manifest' do
+  it.should contain('META-INF/MANIFEST.MF')
+end
+check package(:war).path('WEB-INF'), 'should contain files' do
+  it.should_not be_empty
+end
+check package(:war).path('WEB-INF/classes'), 'should contain classes' do 
+  it.should contain('**/*.class')
+end
+check package(:war).entry('META-INF/MANIFEST'), 'should have license' do
+  it.should contain(/Copyright (C) 2007/)
+end
+check file('target/classes'), 'should contain class files' do
+  it.should contain('**/*.class')
+end
+check file('target/classes/killerapp/Code.class'), 'should exist' do
+  it.should exist
+end
+}}}
+
+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 @it@ returns the subject.
+
+You can also write the first expectation like this:
+
+{{{!ruby
+check do
+  package(:jar).should exist
+end
+}}}
+
+We recommend using the subject and description, they make your build easier to
+read and maintain, and produce better error messages.
+
+There are two methods you can call on just about any object, called @should@
+and @should_not@.  Each method takes an argument, a matcher, and executes that
+matcher.  If the matcher returns false, @should@ fails.  You can figure out
+what @should_not@ does in the same case.
+
+Buildr provides the following matchers:
+
+|_. Method |_. Checks that ... |
+| @exist@   | Given a file task checks that the file (or directory) exists. |
+| @empty@   | Given a file task checks that the file (or directory) is empty. |
+| @contain@ | Given a file task referencing a file, checks its contents, using
+string or regular expression.  For a file task referencing a directory, checks
+that it contains the specified files; global patterns using @*@ and @**@ are
+allowed. |
+
+All these matchers operate against a file task.  If you run them against a
+ZipTask (including JAR, WAR, etc) they can also check the contents of the ZIP
+file.  And as you can see in the examples above, you can also run them against
+a path in a ZIP file, checking its contents as if it was a directory, or
+against an entry in a ZIP file, checking the content of that file.
+
+p(note). The @package@ method returns a package task based on packaging type,
+identifier, group, version and classifier.  The last four are inferred, but if
+you create a package with different specifications (for example, you specify a
+classifier) your checks must call @package@ with the same qualifying arguments
+to return the very same package task.
+
+Buildr expectations are based on RSpec.  "RSpec":http://rspec.info/ is the
+behavior-driven development framework we use to test Buildr itself.  Check the
+RSpec documentation if want to see all the supported matchers, or want to write
+your own.
+
+
+h2. Behaviour-Driven Development
+
+Buildr supports several Behaviour-Driven Development(BDD) frameworks for
+testing your projects.  Buildr follows each framework naming conventions,
+searching for files under the @src/spec/{lang}@ directory.
+
+
+h4. JBehave 
+
+"JBehave":http://jbehave.org/ is a pure Java BDD framework, stories and
+behaviour specifications are written in the Java language. 
+
+To use JBehave in your project you can select it with @test.using :jbehave@.
+
+This framework will search for the following patterns under your project:
+
+{{{
+src/spec/java/**/*Behaviour.java
+}}}
+
+Supports the following options:
+
+|_. Option        |_. Value |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. |
+
+
+h4. RSpec
+
+"RSpec":http://rspec.info/ is the de-facto BDD framework for ruby. It's the
+framework used to test Buildr itself. 
+
+Specifications are written in "Ruby":http://www.ruby-lang.org/en/ language, but
+are run by using "JRuby":http://jruby.codehaus.org/.  That means you have
+access to all your Java classes and any Java or Ruby tool out there.
+
+To use this framework in your project you can select it with @test.using
+:rspec@.
+
+This framework will search for the following patterns under your project:
+
+{{{
+src/spec/ruby/**/*_spec.rb
+}}}
+
+Supports the following options:
+
+|_. Option        |_. Value |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. |
+
+
+h4. EasyB
+
+"EasyB":http://www.easyb.org/ is a BDD framework using
+"Groovy":http://groovy.codehaus.org/. 
+
+Specifications are written in the Groovy language, of course you get seamless
+Java integration as with all things groovy. 
+
+To use this framework in your project you can select it with @test.using
+:easyb@.
+
+This framework will search for the following patterns under your project:
+
+{{{
+src/spec/groovy/**/*Behavior.groovy
+src/spec/groovy/**/*Story.groovy
+}}}
+
+Supports the following options:
+
+|_. Option        |_. Value |
+| @:properties@   | Hash of system properties available to the test case. |
+| @:java_args@    | Arguments passed as is to the JVM. |
+| @:format@       | Report format, either @:txt@ or @:xml@ |
+
+
+Next, let's talk about "customizing your environment and using
+profiles":settings_profiles.html