buildr 1.2.10 → 1.3.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (154) hide show
  1. data/CHANGELOG +566 -268
  2. data/DISCLAIMER +7 -1
  3. data/KEYS +151 -0
  4. data/NOTICE +23 -8
  5. data/README +122 -22
  6. data/Rakefile +49 -229
  7. data/{lib → addon}/buildr/antlr.rb +23 -10
  8. data/addon/buildr/cobertura.rb +232 -0
  9. data/{lib → addon}/buildr/hibernate.rb +20 -4
  10. data/{lib → addon}/buildr/javacc.rb +27 -12
  11. data/addon/buildr/jdepend.rb +60 -0
  12. data/{lib → addon}/buildr/jetty.rb +34 -18
  13. data/addon/buildr/nailgun.rb +892 -0
  14. data/{lib → addon}/buildr/openjpa.rb +23 -6
  15. data/addon/buildr/org/apache/buildr/JettyWrapper$1.class +0 -0
  16. data/addon/buildr/org/apache/buildr/JettyWrapper$BuildrHandler.class +0 -0
  17. data/addon/buildr/org/apache/buildr/JettyWrapper.class +0 -0
  18. data/{lib/buildr/jetty → addon/buildr/org/apache/buildr}/JettyWrapper.java +19 -0
  19. data/{lib → addon}/buildr/xmlbeans.rb +39 -14
  20. data/bin/buildr +21 -7
  21. data/buildr.gemspec +50 -0
  22. data/doc/css/default.css +225 -0
  23. data/doc/css/print.css +95 -0
  24. data/doc/css/syntax.css +43 -0
  25. data/doc/images/apache-incubator-logo.png +0 -0
  26. data/doc/images/buildr-hires.png +0 -0
  27. data/doc/images/buildr.png +0 -0
  28. data/doc/images/note.png +0 -0
  29. data/doc/images/tip.png +0 -0
  30. data/doc/images/zbuildr.tif +0 -0
  31. data/doc/pages/artifacts.textile +317 -0
  32. data/doc/pages/building.textile +501 -0
  33. data/doc/pages/contributing.textile +178 -0
  34. data/doc/pages/download.textile +25 -0
  35. data/doc/pages/extending.textile +229 -0
  36. data/doc/pages/getting_started.textile +337 -0
  37. data/doc/pages/index.textile +63 -0
  38. data/doc/pages/mailing_lists.textile +17 -0
  39. data/doc/pages/more_stuff.textile +367 -0
  40. data/doc/pages/packaging.textile +592 -0
  41. data/doc/pages/projects.textile +449 -0
  42. data/doc/pages/recipes.textile +127 -0
  43. data/doc/pages/settings_profiles.textile +339 -0
  44. data/doc/pages/testing.textile +475 -0
  45. data/doc/pages/troubleshooting.textile +121 -0
  46. data/doc/pages/whats_new.textile +389 -0
  47. data/doc/print.haml +52 -0
  48. data/doc/print.toc.yaml +28 -0
  49. data/doc/scripts/buildr-git.rb +411 -0
  50. data/doc/scripts/install-jruby.sh +44 -0
  51. data/doc/scripts/install-linux.sh +64 -0
  52. data/doc/scripts/install-osx.sh +52 -0
  53. data/doc/site.haml +55 -0
  54. data/doc/site.toc.yaml +44 -0
  55. data/lib/buildr.rb +28 -45
  56. data/lib/buildr/core.rb +27 -0
  57. data/lib/buildr/core/application.rb +373 -0
  58. data/lib/buildr/core/application_cli.rb +134 -0
  59. data/lib/{core → buildr/core}/build.rb +91 -77
  60. data/lib/{core → buildr/core}/checks.rb +116 -95
  61. data/lib/buildr/core/common.rb +155 -0
  62. data/lib/buildr/core/compile.rb +594 -0
  63. data/lib/buildr/core/environment.rb +120 -0
  64. data/lib/buildr/core/filter.rb +258 -0
  65. data/lib/{core → buildr/core}/generate.rb +22 -5
  66. data/lib/buildr/core/help.rb +118 -0
  67. data/lib/buildr/core/progressbar.rb +156 -0
  68. data/lib/{core → buildr/core}/project.rb +468 -213
  69. data/lib/buildr/core/test.rb +690 -0
  70. data/lib/{core → buildr/core}/transports.rb +107 -127
  71. data/lib/buildr/core/util.rb +235 -0
  72. data/lib/buildr/ide.rb +19 -0
  73. data/lib/{java → buildr/ide}/eclipse.rb +86 -60
  74. data/lib/{java → buildr/ide}/idea.ipr.template +16 -0
  75. data/lib/buildr/ide/idea.rb +194 -0
  76. data/lib/buildr/ide/idea7x.ipr.template +290 -0
  77. data/lib/buildr/ide/idea7x.rb +210 -0
  78. data/lib/buildr/java.rb +26 -0
  79. data/lib/buildr/java/ant.rb +71 -0
  80. data/lib/buildr/java/bdd_frameworks.rb +267 -0
  81. data/lib/buildr/java/commands.rb +210 -0
  82. data/lib/buildr/java/compilers.rb +432 -0
  83. data/lib/buildr/java/deprecated.rb +141 -0
  84. data/lib/buildr/java/groovyc.rb +137 -0
  85. data/lib/buildr/java/jruby.rb +99 -0
  86. data/lib/buildr/java/org/apache/buildr/BuildrNail$Main.class +0 -0
  87. data/lib/buildr/java/org/apache/buildr/BuildrNail.class +0 -0
  88. data/lib/buildr/java/org/apache/buildr/BuildrNail.java +41 -0
  89. data/lib/buildr/java/org/apache/buildr/JavaTestFilter.class +0 -0
  90. data/lib/buildr/java/org/apache/buildr/JavaTestFilter.java +116 -0
  91. data/lib/buildr/java/packaging.rb +706 -0
  92. data/lib/{java → buildr/java}/pom.rb +20 -4
  93. data/lib/buildr/java/rjb.rb +142 -0
  94. data/lib/buildr/java/test_frameworks.rb +290 -0
  95. data/lib/buildr/java/version_requirement.rb +172 -0
  96. data/lib/buildr/packaging.rb +21 -0
  97. data/lib/{java → buildr/packaging}/artifact.rb +170 -179
  98. data/lib/buildr/packaging/artifact_namespace.rb +957 -0
  99. data/lib/buildr/packaging/artifact_search.rb +140 -0
  100. data/lib/buildr/packaging/gems.rb +102 -0
  101. data/lib/buildr/packaging/package.rb +233 -0
  102. data/lib/{tasks → buildr/packaging}/tar.rb +18 -1
  103. data/lib/{tasks → buildr/packaging}/zip.rb +153 -105
  104. data/rakelib/apache.rake +126 -0
  105. data/rakelib/changelog.rake +56 -0
  106. data/rakelib/doc.rake +103 -0
  107. data/rakelib/package.rake +44 -0
  108. data/rakelib/release.rake +53 -0
  109. data/rakelib/rspec.rake +81 -0
  110. data/rakelib/rubyforge.rake +45 -0
  111. data/rakelib/scm.rake +49 -0
  112. data/rakelib/setup.rake +59 -0
  113. data/rakelib/stage.rake +45 -0
  114. data/spec/application_spec.rb +316 -0
  115. data/spec/archive_spec.rb +494 -0
  116. data/spec/artifact_namespace_spec.rb +635 -0
  117. data/spec/artifact_spec.rb +738 -0
  118. data/spec/build_spec.rb +193 -0
  119. data/spec/checks_spec.rb +537 -0
  120. data/spec/common_spec.rb +579 -0
  121. data/spec/compile_spec.rb +561 -0
  122. data/spec/groovy_compilers_spec.rb +239 -0
  123. data/spec/java_bdd_frameworks_spec.rb +238 -0
  124. data/spec/java_compilers_spec.rb +446 -0
  125. data/spec/java_packaging_spec.rb +1042 -0
  126. data/spec/java_test_frameworks_spec.rb +414 -0
  127. data/spec/packaging_helper.rb +63 -0
  128. data/spec/packaging_spec.rb +589 -0
  129. data/spec/project_spec.rb +739 -0
  130. data/spec/sandbox.rb +116 -0
  131. data/spec/scala_compilers_spec.rb +239 -0
  132. data/spec/spec.opts +6 -0
  133. data/spec/spec_helpers.rb +283 -0
  134. data/spec/test_spec.rb +871 -0
  135. data/spec/transport_spec.rb +300 -0
  136. data/spec/version_requirement_spec.rb +115 -0
  137. metadata +188 -77
  138. data/lib/buildr/cobertura.rb +0 -89
  139. data/lib/buildr/jdepend.rb +0 -40
  140. data/lib/buildr/jetty/JettyWrapper$1.class +0 -0
  141. data/lib/buildr/jetty/JettyWrapper$BuildrHandler.class +0 -0
  142. data/lib/buildr/jetty/JettyWrapper.class +0 -0
  143. data/lib/buildr/scala.rb +0 -368
  144. data/lib/core/application.rb +0 -188
  145. data/lib/core/common.rb +0 -562
  146. data/lib/core/help.rb +0 -72
  147. data/lib/core/rake_ext.rb +0 -81
  148. data/lib/java/ant.rb +0 -71
  149. data/lib/java/compile.rb +0 -589
  150. data/lib/java/idea.rb +0 -159
  151. data/lib/java/java.rb +0 -432
  152. data/lib/java/packaging.rb +0 -581
  153. data/lib/java/test.rb +0 -795
  154. data/lib/tasks/concat.rb +0 -35
@@ -0,0 +1,339 @@
1
+ h1. Settings/Profiles
2
+
3
+
4
+ h2. Environment Variables
5
+
6
+ Buildr uses several environment variables that help you control how it works.
7
+ Some environment variables you will only set once or change infrequently. You
8
+ can set these in your profile, OS settings or any tool you use to launch Buildr
9
+ (e.g. continuous integration).
10
+
11
+ For example:
12
+
13
+ {{{!sh
14
+ $ export HTTP_PROXY=http://myproxy:8080
15
+ }}}
16
+
17
+ There are other environment variables you will want to set when running Buildr,
18
+ for example, to do a full build without running the tests:
19
+
20
+ {{{!sh
21
+ $ buildr test=no
22
+ }}}
23
+
24
+ For convenience, when you set environment variables on the command line, the
25
+ variable name is case insensitive, you can use either @test=no@ or @TEST=no@.
26
+ Any other way (@export@, @ENV@, etc) the variable names are case sensitive.
27
+
28
+ You can also set environment variables from within your Buildfile. For
29
+ example, if you discover that building your project requires gobs of JVM heap
30
+ space, and you want all other team members to run with the same settings:
31
+
32
+ {{{!ruby
33
+ # This project builds a lot of code.
34
+ ENV['JAVA_OPTS'] ||= '-Xms1g -Xmx1g'
35
+ }}}
36
+
37
+ Make sure to set any environment variables at the very top of the Buildfile,
38
+ above any Ruby statement (even @require@).
39
+
40
+ p(tip). Using @||=@ sets the environment variable, if not already set, so
41
+ it's still possible for other developers to override this environment variable
42
+ without modifying the Buildfile.
43
+
44
+ Buildr supports the following environment variables:
45
+
46
+ |_. Variable |_. Description |
47
+ | @BUILDR_ENV@ | Environment name (development, production, test, etc).
48
+ Another way to set this is using the @-e@ command line option. |
49
+ | @DEBUG@ | Set to @no/off@ if you want Buildr to compile without
50
+ debugging information (default when running the @release@ task, see
51
+ "Compiling":building.html#compiling). |
52
+ | @HOME@ | Your home directory. |
53
+ | @HTTP_PROXY@ | URL for HTTP proxy server (see "Specifying
54
+ Repositories":artifacts.html#specifying_repositories). |
55
+ | @JAVA_HOME@ | Points to your JDK, required when using Java and Ant. |
56
+ | @JAVA_OPTS@ | Command line options to pass to the JDK (e.g. @'-Xms1g'@). |
57
+ | @M2_REPO@ | Location of the Maven2 local repository. Defaults to the
58
+ @.m2@ directory in your home directory (@ENV['HOME']@). |
59
+ | @NO_PROXY@ | Comma separated list of hosts and domain that should not be
60
+ proxied (see "Specifying Repositories":artifacts.html#specifying_repositories). |
61
+ | @TEST@ | Set to @no/off@ to tell Buildr to skip tests, or @all@ to
62
+ tell Buildr to run all tests and ignore failures (see "Running
63
+ Tests":testing.html#running_tests). |
64
+ | @USER@ | Tasks that need your user name, for example to log to remote
65
+ servers, will use this environment variable. |
66
+
67
+ p(note). Buildr does not check any of the arguments in @JAVA_OPTS@. A common
68
+ mistake is to pass an option like @mx512mb@, where it should be @Xmx512mb@.
69
+ Make sure to double check @JAVA_OPTS@.
70
+
71
+ Some extensions may use additional environment variables, and of course, you
72
+ can always add your own. This example uses two environment variables for
73
+ specifying the username and password:
74
+
75
+ {{{!ruby
76
+ repositories.upload_to[:username] = ENV['USERNAME']
77
+ repositories.upload_to[:password] = ENV['PASSWORD']
78
+ }}}
79
+
80
+
81
+ h2. Personal Settings
82
+
83
+ Some things clearly do not belong in the Buildfile. For example, the username
84
+ and password you use to upload releases. If you're working in a team or on an
85
+ open source project, you'd want to keep these in a separate place.
86
+
87
+ You may want to use personal settings for picking up a different location for
88
+ the local repository, or use a different set of preferred remote repositories,
89
+ and so forth.
90
+
91
+ The prefered way to store personal settings is to create a @.buildr/settings.yaml@
92
+ file under your home directory. Settings stored there will be applied the same
93
+ across all builds.
94
+
95
+ Here's an example @settings.yaml@:
96
+
97
+ {{{!yaml
98
+ # The repositories hash is read automatically by buildr.
99
+ repositories:
100
+
101
+ # customize user local maven2 repository location
102
+ local: some/path/to/my_repo
103
+
104
+ # prefer the local or nearest mirrors
105
+ remote:
106
+ - https://intra.net/maven2
107
+ - http://example.com
108
+
109
+ relase_to:
110
+ url: http://intra.net/maven2
111
+ username: john
112
+ password: secret
113
+
114
+ # You can place settings of your own, and reference them
115
+ # on buildfiles.
116
+ im:
117
+ server: jabber.company.com
118
+ usr: notifier@company-jabber.com
119
+ pwd: secret
120
+ }}}
121
+
122
+ Later your buildfile or addons can reference user preferences using the
123
+ hash returned by the @Buildr.settings.user@ accessor.
124
+
125
+ {{{!ruby
126
+ task 'relase-notification' do
127
+ usr, pwd, server = settings.user['im'].values_at('usr', 'pwd', 'server')
128
+ jabber = JabberAPI.new(server, usr, pwd)
129
+ jabber.msg("We are pleased to announce the last stable version #{VERSION}")
130
+ end
131
+ }}}
132
+
133
+
134
+ h2. Build Settings
135
+
136
+ Build settings are local to the project being built, and are placed in the
137
+ @build.yaml@ file located in the same directory that the @buildfile@. Normally
138
+ this file would be managed by the project revision control system, so settings
139
+ here are shared between developers.
140
+
141
+ They help keep the buildfile and build.yaml file simple and readable, working
142
+ to the advantages of each one. Example for build settings are gems,
143
+ repositories and artifacts used by that build.
144
+
145
+ {{{!yaml
146
+ # This project requires the following ruby gems, buildr addons
147
+ gems:
148
+ # Suppose we want to notify developers when testcases fail.
149
+ - buildr-twitter-notifier-addon >=1
150
+ # we test with ruby mock objects
151
+ - mocha
152
+ - ci_reporter
153
+
154
+ # The artifact declarations will be automatically loaded by buildr, so that
155
+ # you can reference artifacts by name (a ruby-symbol) on your buildfile.
156
+ artifacts:
157
+ spring: org.springframework:spring:jar:2.0
158
+ log4j: log4j:log4j:jar:1.0
159
+ j2ee: geronimo-spec:geronimo-spec-j2ee:jar:1.4-rc4
160
+
161
+ # Of course project settings can be defined here
162
+ twitter:
163
+ notify:
164
+ test_failure: unless-modified
165
+ compile_failure: never
166
+ developers:
167
+ - joe
168
+ - jane
169
+
170
+ jira:
171
+ uri: https://jira.corp.org
172
+ }}}
173
+
174
+ When buildr is loaded, required ruby gems will be installed if needed, thus adding
175
+ features like the imaginary twitter notifier addon.
176
+
177
+ Artifacts defined on @build.yaml@ can be referenced on your buildfile by supplying
178
+ the ruby symbol to the @Buildr.artifact@ and @Buildr.artifacts@ methods.
179
+ The @compile.with@, @test.with@ methods can also be given these names.
180
+
181
+ {{{!ruby
182
+ define 'my_project' do
183
+ compile.with artifacts(:log4j, :j2ee)
184
+ test.with :spring, :j2ee
185
+ end
186
+ }}}
187
+
188
+ Build settings can be retreived using the @Buildr.settings.build@ accessor.
189
+
190
+ {{{!ruby
191
+ task 'create_patch' do
192
+ patch = Git.create_patch :interactive => true
193
+ if patch && agree("Would you like to request inclusion of #{patch}")
194
+ jira = Jira.new( Buildr.settings.build['jira']['uri'] ) # submit a patch
195
+ jira.create(:improvement, patch.summary, :attachment => patch.blob)
196
+ end
197
+ end
198
+ }}}
199
+
200
+ h2. Non constant settings
201
+
202
+ Before loading the Buildfile, Buildr will attempt to load two other files: the
203
+ @buildr.rb@ file it finds in your home directory, followed by the @buildr.rb@
204
+ file it finds in the build directory.
205
+
206
+ The loading order allows you to place global settings that affect all your
207
+ builds in your home directory's @buildr.rb@, but also over-ride those with
208
+ settings for a given project.
209
+
210
+ Here's an example @buildr.rb@:
211
+
212
+ {{{!ruby
213
+ # Only I should know that
214
+ repositories.upload_to[:username] = 'assaf'
215
+ repositories.upload_to[:password] = 'supersecret'
216
+ # Search here first, it's faster
217
+ repositories.remote << 'http://inside-the-firewall'
218
+ }}}
219
+
220
+
221
+ h2. Environments
222
+
223
+ One common use case is adapting the build to different environments. For
224
+ example, to compile code with debugging information during development and
225
+ testing, but strip it for production. Another example is using different
226
+ databases for development, testing and production, or running services at
227
+ different URLs.
228
+
229
+ So let's start by talking about the build environment. Buildr has a global
230
+ attributes that indicates which environment it's running in, accessible from the
231
+ @environment@ method. You can set the current build environment in one of two
232
+ ways. Using the @-e/--environment@ command line option:
233
+
234
+ {{{!sh
235
+ $ buildr -e test
236
+ (in /home/john/project, test)
237
+ }}}
238
+
239
+ Or by setting the environment variable @BUILDR_ENV@:
240
+
241
+ {{{!
242
+ $ export BUILDR_ENV=production
243
+ $ buildr
244
+ (in /home/john/project, production)
245
+ }}}
246
+
247
+ Unless you tell it otherwise, Buildr assumes you're developing and sets the
248
+ environment to @development@.
249
+
250
+ Here's a simple example for handling different environments within the
251
+ Buildfile:
252
+
253
+ {{{!ruby
254
+ project 'db-module' do
255
+ db = (environment == 'production' ? 'oracle' : 'hsql')
256
+ resources.from(_(:source, :main, db))
257
+ end
258
+ }}}
259
+
260
+ We recommend picking a convention for your different environments and following
261
+ it across all your projects. For example:
262
+
263
+ |_. Environment |_. Use when ... |
264
+ | development | Developing on your machine. |
265
+ | test | Running in test environment, continuous integration. |
266
+ | production | Building for release/production. |
267
+
268
+
269
+ h2. Profiles
270
+
271
+ Different environments may require different configurations, some you will want
272
+ to control with code, others you will want to specify in the profiles file.
273
+
274
+ The profiles file is a YAML file called @profiles.yaml@ that you place in the
275
+ same directory as the Buildfile. We selected YAML because it's easier to read
276
+ and edit than XML.
277
+
278
+ For example, to support three different database configurations, we could write:
279
+
280
+ {{{!yaml
281
+ # HSQL, don't bother storing to disk.
282
+ development:
283
+ db: hsql
284
+ jdbc: hsqldb:mem:devdb
285
+
286
+ # Make sure we're not messing with bigstrong.
287
+ test:
288
+ db: oracle
289
+ jdbc: oracle:thin:@localhost:1521:test
290
+
291
+ # The real deal.
292
+ production:
293
+ db: oracle
294
+ jdbc: oracle:thin:@bigstrong:1521:mighty
295
+ }}}
296
+
297
+ Here's a simple example for a buildfile that uses the profile information:
298
+
299
+ {{{!ruby
300
+ project 'db-module' do
301
+ # Copy SQL files specific for the database we're using,
302
+ # for example, everything under src/main/hsql.
303
+ resources.from(_(:source, :main, profile['db']))
304
+ # Set the JDBC URL in copied resource files (config.xml needs this).
305
+ resources.filter :jdbc=>profile['jdbc']
306
+ end
307
+ }}}
308
+
309
+ The @profile@ method returns the current profile, selected based on the current
310
+ "environment":#environments. You can get a list of all profiles by calling
311
+ @profiles@.
312
+
313
+ When you run the above example in @development@, the current profile will
314
+ return the hash @{ 'db'=>'hsql', 'jdbc'=>'hsqldb:mem:devdb' }@.
315
+
316
+ We recommend following conventions and using the same environments in all your
317
+ projects, but sometimes the profiles end up being the same, so here's a trick
318
+ you can use to keep your profiles DRY.
319
+
320
+ YAML allows you to use anchors (@&@), similar to ID attributes in XML,
321
+ reference the anchored element (@*@) elsewhere, and merge one element into
322
+ another (@<<@). For example:
323
+
324
+
325
+ {{{!yaml
326
+ # We'll reference this one as common.
327
+ development: &common
328
+ db: hsql
329
+ jdbc: hsqldb:mem:devdb
330
+ resources:
331
+ copyright: Me (C) 2008
332
+ # Merge the values from common, override JDBC URL.
333
+ test:
334
+ <<: *common
335
+ jdbc: hsqldb:file:testdb
336
+ }}}
337
+
338
+ You can "learn more about YAML here":http://www.yaml.org, and use this
339
+ handy "YAML quick reference":http://www.yaml.org/refcard.html.
@@ -0,0 +1,475 @@
1
+ h1. Testing
2
+
3
+ Untested code is broken code, so we take testing seriously. Off the bat you
4
+ get to use either JUnit or TestNG for writing unit tests and integration tests.
5
+ And you can also add your own framework, or even script tests using Ruby. But
6
+ first, let's start with the basics.
7
+
8
+
9
+ h2. Writing Tests
10
+
11
+ Each project has a @TestTask@ that you can access using the @test@ method.
12
+ @TestTask@ reflects on the fact that each project has one task responsible for
13
+ getting the tests to run and acting on the results. But in fact there are
14
+ several tasks that do all the work, and a @test@ task coordinates all of that.
15
+
16
+ The first two tasks to execute are @test.compile@ and @test.resources@. They
17
+ work similar to @compile@ and @resources@, but uses a different set of
18
+ directories. For example, Java tests compile from the @src/test/java@
19
+ directory into the @target/test/classes@ directory, while resources are copied
20
+ from @src/test/resources@ into @target/test/resources@.
21
+
22
+ The @test.compile@ task will run the @compile@ task first, then use the same
23
+ dependencies to compile the test classes. That much you already assumed. It
24
+ also adds the test framework (e.g. JUnit, TestNG) and JMock to the dependency
25
+ list. Less work for you.
26
+
27
+ If you need more dependencies, the best way to add them is by calling
28
+ @test.with@. This method adds dependencies to both @compile.dependencies@ (for
29
+ compiling) and @test.dependencies@ (for running). You can manage these two
30
+ dependency lists separately, but using @test.with@ is good enough in more
31
+ cases.
32
+
33
+ Once compiled, the @test@ task runs all the tests.
34
+
35
+
36
+ h2. Using JUnit
37
+
38
+ The default test framework for Java projects is JUnit 4.
39
+
40
+ When you use JUnit, the dependencies includes JUnit, and Buildr picks up all
41
+ test classes from the project by looking for classes that either subclass
42
+ @junit.framework.TestCase@, include methods annotated with @org.junit.Test@,
43
+ or test suites annotated with @org.org.junit.runner.RunWith@.
44
+
45
+ The JUnit test framework supports the following options:
46
+
47
+ |_. Option |_. Value |
48
+ | @:fork@ | VM forking, defaults to true. |
49
+ | @:clonevm@ | If true clone the VM each time it is forked. |
50
+ | @:properties@ | Hash of system properties available to the test case. |
51
+ | @:environment@ | Hash of environment variables available to the test case. |
52
+ | @:java_args@ | Arguments passed as is to the JVM. |
53
+
54
+ For example, to pass properties to the test case:
55
+
56
+ {{{!ruby
57
+ test.using :properties=>{ :currency=>'USD' }
58
+ }}}
59
+
60
+ There are benefits to running test cases in separate VMs. The default forking
61
+ mode is @:once@, and you can change it by setting the @:fork@ option.
62
+
63
+ |_. :fork=> |_. Behavior |
64
+ | @:once@ | Create one VM to run all test classes in the project, separate
65
+ VMs for each project. |
66
+ | @:each@ | Create one VM for each test case class. Slow but provides the
67
+ best isolation between test classes. |
68
+ | @false@ | Without forking, Buildr runs all test cases in a single VM. This
69
+ option runs fastest, but at the risk of running out of memory and causing test
70
+ cases to interfere with each other. |
71
+
72
+ You can see your tests running in the console, and if any tests fail, Buildr
73
+ will show a list of the failed test classes. In addition, JUnit produces text
74
+ and XML report files in the project's @reports/junit@ directory. You can use
75
+ that to get around too-much-stuff-in-my-console, or when using an automated
76
+ test system.
77
+
78
+ In addition, you can get a consolidated XML or HTML report by running the
79
+ @junit:report@ task. For example:
80
+
81
+ {{{!sh
82
+ $ buildr test junit:report test=all
83
+ $ firefox report/junit/html/index.html
84
+ }}}
85
+
86
+ The @junit:report@ task generates a report from all tests run so far. If you
87
+ run tests in a couple of projects, it will generate a report only for these two
88
+ projects. The example above runs tests in all the projects before generating
89
+ the reports.
90
+
91
+
92
+ h2. Using TestNG
93
+
94
+ You can also use TestNG in your project by telling your project to use TestNG:
95
+
96
+ {{{!ruby
97
+ test.using :testng
98
+ }}}
99
+
100
+ Like all other options you can set with @test.using@, it affects the projects
101
+ and all its sub-projects, so you only need to do this once at the top-most
102
+ project to use TestNG throughout. You can also mix TestNG and JUnit by setting
103
+ different projects to use different frameworks, but you can't mix both
104
+ frameworks in the same project. (And yes, @test.using :junit@ will switch a
105
+ project back to using JUnit)
106
+
107
+ TestNG works much like JUnit, it gets included in the dependency list, Buildr
108
+ picks test classes that contain methods annotated with
109
+ @org.testng.annotations.Test@, and generates test reports in
110
+ the @reports/testng@ directory. At the moment we don't have consolidated HTML
111
+ reports for TestNG.
112
+
113
+ The TestNG test framework supports the following options:
114
+
115
+ |_. Option |_. Value |
116
+ | @:properties@ | Hash of system properties available to the test case. |
117
+ | @:java_args@ | Arguments passed as is to the JVM. |
118
+
119
+
120
+ h2. Excluding Tests and Ignoring Failures
121
+
122
+ If you have a lot of tests that are failing or just hanging there collecting
123
+ dusts, you can tell Buildr to ignore them. You can either tell Buildr to only
124
+ run specific tests, for example:
125
+
126
+ {{{!ruby
127
+ test.include 'com.acme.tests.passing.*'
128
+ }}}
129
+
130
+ Or tell it to exclude specific tests, for example:
131
+
132
+ {{{!ruby
133
+ test.exclude '*FailingTest', '*FailingWorseTest'
134
+ }}}
135
+
136
+ Note that we're always using the package qualified class name, and you can use
137
+ star (@*@) to substitute for any set of characters.
138
+
139
+ When tests fail, Buildr fails the @test@ task. This is usually a good thing,
140
+ but you can also tell Buildr to ignore failures by resetting the
141
+ @:fail_on_failure@ option:
142
+
143
+ {{{!ruby
144
+ test.using :fail_on_failure=>false
145
+ }}}
146
+
147
+ Besides giving you a free pass to ignore failures, you can use it for other
148
+ causes, for example, to be somewhat forgiving:
149
+
150
+ {{{!ruby
151
+ test do
152
+ fail 'More than 3 tests failed!' if test.failed_tests.size > 3
153
+ end
154
+ }}}
155
+
156
+ The @failed_tests@ collection holds the names of all classes with failed tests.
157
+ And there's @classes@, which holds the names of all test classes. Ruby
158
+ arithmetic allows you to get the name of all passed test classes with a simple
159
+ @test.classes – test.failed_tests@. We'll let you imagine creative use for
160
+ these two.
161
+
162
+
163
+ h2. Running Tests
164
+
165
+ It's a good idea to run tests every time you change the source code, so we
166
+ wired the @build@ task to run the @test@ task at the end of the build. And
167
+ conveniently enough, the @build@ task is the default task, so another way to
168
+ build changes in your code and run your tests:
169
+
170
+ {{{!sh
171
+ $ buildr
172
+ }}}
173
+
174
+ That only works with the local @build@ task and any local task that depends on
175
+ it, like @package@, @install@ and @upload@. Each project also has its own
176
+ @build@ task that does not invoke the @test@ task, so @buildr build@ will run
177
+ the tests cases, but @buildr foo:build@ will not.
178
+
179
+ While it's a good idea to always run your tests, it's not always possible.
180
+ There are two ways you can get @build@ to not run the @test@ task. You can set
181
+ the environment variable @test@ to @no@ (but @skip@ and @off@ will also work).
182
+ You can do that when running Buildr:
183
+
184
+ {{{!sh
185
+ $ buildr test=no
186
+ }}}
187
+
188
+ Or set it once in your environment:
189
+
190
+ {{{!sh
191
+ $ export TEST=no
192
+ $ buildr
193
+ }}}
194
+
195
+ If you're feeling really adventurous, you can also disable tests from your
196
+ Buildfile or @buildr.rb@ file, by setting @options.test = false@. We didn't say
197
+ it's a good idea, we're just giving you the option.
198
+
199
+ The @test@ task is just smart enough to run all the tests it finds, but will
200
+ accept include/exclude patterns. Often enough you're only working on one
201
+ broken test and you only want to run that one test. Better than changing your
202
+ Buildfile, you can run the @test@ task with a pattern. For example:
203
+
204
+ {{{!sh
205
+ $ buildr test:KillerAppTest
206
+ }}}
207
+
208
+ Buildr will then run only tests that match the pattern @KillerAppTest@. It
209
+ uses pattern matching, so @test:Foo@ will run @com.acme.FooTest@ and
210
+ @com.acme.FooBarTest@. With Java, you can use this to pick a class name, or a
211
+ package name to run all tests in that package, or any such combination. In
212
+ fact, you can specify several patterns separated with commas. For example:
213
+
214
+ {{{!sh
215
+ $ buildr test:FooTest,BarTest
216
+ }}}
217
+
218
+ As you probably noticed, Buildr will stop your build at the first test that
219
+ fails. We think it's a good idea, except when it's not. If you're using a
220
+ continuous build system, you'll want a report of all the failed tests without
221
+ stopping at the first failure. To make that happen, set the environment
222
+ variable @test@ to "all", or the Buildr @options.test@ option to @:all@. For
223
+ example:
224
+
225
+ {{{!sh
226
+ $ buildr package test=all
227
+ }}}
228
+
229
+ We're using @package@ and not @build@ above. When using a continuous build
230
+ system, you want to make sure that packages are created, contain the right
231
+ files, and also run the integration tests.
232
+
233
+
234
+ h2. Integration Tests
235
+
236
+ So far we talked about unit tests. Unit tests are run in isolation on the
237
+ specific project they test, in an isolated environment, generally with minimal
238
+ setup and teardown. You get a sense of that when we told you tests run after
239
+ the @build@ task, and include JMock in the dependency list.
240
+
241
+ In contrast, integration tests are run with a number of components, in an
242
+ environment that resembles production, often with more complicates setup and
243
+ teardown procedures. In this section we'll talk about the differences between
244
+ running unit and integration tests.
245
+
246
+ You write integration tests much the same way as you write unit tests, using
247
+ @test.compile@ and @test.resources@. However, you need to tell Buildr that
248
+ your tests will execute during integration test. To do so, add the following
249
+ line in your project definition:
250
+
251
+ {{{!ruby
252
+ test.using :integration
253
+ }}}
254
+
255
+ Typically you'll use unit tests in projects that create internal modules, such
256
+ as JARs, and integration tests in projects that create components, such as WARs
257
+ and EARs. You only need to use the @:integration@ option with the later.
258
+
259
+ To run integration tests on the current project:
260
+
261
+ {{{!sh
262
+ $ buildr integration
263
+ }}}
264
+
265
+ You can also run specific tests cases, for example:
266
+
267
+ {{{!sh
268
+ $ buildr integration:ClientTest
269
+ }}}
270
+
271
+ If you run the @package@ task (or any task that depends on it, like @install@
272
+ and @upload@), Buildr will first run the @build@ task and all its unit tests,
273
+ and then create the packages and run the integration tests. That gives you
274
+ full coverage for your tests and ready to release packages. As with unit
275
+ tests, you can set the environment variable @test@ to "no" to skip integration
276
+ tests, or "all" to ignore failures.
277
+
278
+
279
+ h2. Using Setup and Teardown
280
+
281
+ Some tests need you to setup an environment before they run, and tear it down
282
+ afterwards. The test frameworks (JUnit, TestNG) allow you to do that for each
283
+ test. Buildr provides two additional mechanisms for dealing with more
284
+ complicated setup and teardown procedures.
285
+
286
+ Integration tests run a setup task before the tests, and a teardown task
287
+ afterwards. You can use this task to setup a Web server for testing your Web
288
+ components, or a database server for testing persistence. You can access
289
+ either task by calling @integration.setup@ and @integration.teardown@. For
290
+ example:
291
+
292
+ {{{!ruby
293
+ integration.setup { server.start ; server.deploy }
294
+ integration.teardown { server.stop }
295
+ }}}
296
+
297
+ Depending on your build, you may want to enhance the setup/teardown tasks from
298
+ within a project, for example, to populate the database with data used by that
299
+ project's test, or from outside the project definition, for example, to start
300
+ and stop the Web server.
301
+
302
+ Likewise, each project has its own setup and teardown tasks that are run before
303
+ and after tests for that specific project. You can access these tasks using
304
+ @test.setup@ and @test.teardown@.
305
+
306
+
307
+ h2. Testing Your Build
308
+
309
+ So you got the build running and all the tests pass, binaries are shipping when
310
+ you find out some glaring omissions. The license file is empty, the localized
311
+ messages for Japanese are missing, the CSS files are not where you expect them
312
+ to be. The fact is, some errors slip by unit and integration tests. So how do
313
+ we make sure the same mistake doesn't happen again?
314
+
315
+ Each project has a @check@ task that runs just after packaging. You can use
316
+ this task to verify that your build created the files you wanted it to create.
317
+ And to make it extremely convenient, we introduced the notion of expectations.
318
+
319
+ You use the @check@ method to express and expectation. Buildr will then run
320
+ all these expectations against your project, and fail at the first expectation
321
+ that doesn't match. An expectation says three things. Let's look at a few
322
+ examples:
323
+
324
+ {{{!ruby
325
+ check package(:war), 'should exist' do
326
+ it.should exist
327
+ end
328
+ check package(:war), 'should contain a manifest' do
329
+ it.should contain('META-INF/MANIFEST.MF')
330
+ end
331
+ check package(:war).path('WEB-INF'), 'should contain files' do
332
+ it.should_not be_empty
333
+ end
334
+ check package(:war).path('WEB-INF/classes'), 'should contain classes' do
335
+ it.should contain('**/*.class')
336
+ end
337
+ check package(:war).entry('META-INF/MANIFEST'), 'should have license' do
338
+ it.should contain(/Copyright (C) 2007/)
339
+ end
340
+ check file('target/classes'), 'should contain class files' do
341
+ it.should contain('**/*.class')
342
+ end
343
+ check file('target/classes/killerapp/Code.class'), 'should exist' do
344
+ it.should exist
345
+ end
346
+ }}}
347
+
348
+ The first argument is the subject, or the project if you skip the first
349
+ argument. The second argument is the description, optional, but we recommend
350
+ using it. The method @it@ returns the subject.
351
+
352
+ You can also write the first expectation like this:
353
+
354
+ {{{!ruby
355
+ check do
356
+ package(:jar).should exist
357
+ end
358
+ }}}
359
+
360
+ We recommend using the subject and description, they make your build easier to
361
+ read and maintain, and produce better error messages.
362
+
363
+ There are two methods you can call on just about any object, called @should@
364
+ and @should_not@. Each method takes an argument, a matcher, and executes that
365
+ matcher. If the matcher returns false, @should@ fails. You can figure out
366
+ what @should_not@ does in the same case.
367
+
368
+ Buildr provides the following matchers:
369
+
370
+ |_. Method |_. Checks that ... |
371
+ | @exist@ | Given a file task checks that the file (or directory) exists. |
372
+ | @empty@ | Given a file task checks that the file (or directory) is empty. |
373
+ | @contain@ | Given a file task referencing a file, checks its contents, using
374
+ string or regular expression. For a file task referencing a directory, checks
375
+ that it contains the specified files; global patterns using @*@ and @**@ are
376
+ allowed. |
377
+
378
+ All these matchers operate against a file task. If you run them against a
379
+ ZipTask (including JAR, WAR, etc) they can also check the contents of the ZIP
380
+ file. And as you can see in the examples above, you can also run them against
381
+ a path in a ZIP file, checking its contents as if it was a directory, or
382
+ against an entry in a ZIP file, checking the content of that file.
383
+
384
+ p(note). The @package@ method returns a package task based on packaging type,
385
+ identifier, group, version and classifier. The last four are inferred, but if
386
+ you create a package with different specifications (for example, you specify a
387
+ classifier) your checks must call @package@ with the same qualifying arguments
388
+ to return the very same package task.
389
+
390
+ Buildr expectations are based on RSpec. "RSpec":http://rspec.info/ is the
391
+ behavior-driven development framework we use to test Buildr itself. Check the
392
+ RSpec documentation if want to see all the supported matchers, or want to write
393
+ your own.
394
+
395
+
396
+ h2. Behaviour-Driven Development
397
+
398
+ Buildr supports several Behaviour-Driven Development(BDD) frameworks for
399
+ testing your projects. Buildr follows each framework naming conventions,
400
+ searching for files under the @src/spec/{lang}@ directory.
401
+
402
+
403
+ h4. JBehave
404
+
405
+ "JBehave":http://jbehave.org/ is a pure Java BDD framework, stories and
406
+ behaviour specifications are written in the Java language.
407
+
408
+ To use JBehave in your project you can select it with @test.using :jbehave@.
409
+
410
+ This framework will search for the following patterns under your project:
411
+
412
+ {{{
413
+ src/spec/java/**/*Behaviour.java
414
+ }}}
415
+
416
+ Supports the following options:
417
+
418
+ |_. Option |_. Value |
419
+ | @:properties@ | Hash of system properties available to the test case. |
420
+ | @:java_args@ | Arguments passed as is to the JVM. |
421
+
422
+
423
+ h4. RSpec
424
+
425
+ "RSpec":http://rspec.info/ is the de-facto BDD framework for ruby. It's the
426
+ framework used to test Buildr itself.
427
+
428
+ Specifications are written in "Ruby":http://www.ruby-lang.org/en/ language, but
429
+ are run by using "JRuby":http://jruby.codehaus.org/. That means you have
430
+ access to all your Java classes and any Java or Ruby tool out there.
431
+
432
+ To use this framework in your project you can select it with @test.using
433
+ :rspec@.
434
+
435
+ This framework will search for the following patterns under your project:
436
+
437
+ {{{
438
+ src/spec/ruby/**/*_spec.rb
439
+ }}}
440
+
441
+ Supports the following options:
442
+
443
+ |_. Option |_. Value |
444
+ | @:properties@ | Hash of system properties available to the test case. |
445
+ | @:java_args@ | Arguments passed as is to the JVM. |
446
+
447
+
448
+ h4. EasyB
449
+
450
+ "EasyB":http://www.easyb.org/ is a BDD framework using
451
+ "Groovy":http://groovy.codehaus.org/.
452
+
453
+ Specifications are written in the Groovy language, of course you get seamless
454
+ Java integration as with all things groovy.
455
+
456
+ To use this framework in your project you can select it with @test.using
457
+ :easyb@.
458
+
459
+ This framework will search for the following patterns under your project:
460
+
461
+ {{{
462
+ src/spec/groovy/**/*Behavior.groovy
463
+ src/spec/groovy/**/*Story.groovy
464
+ }}}
465
+
466
+ Supports the following options:
467
+
468
+ |_. Option |_. Value |
469
+ | @:properties@ | Hash of system properties available to the test case. |
470
+ | @:java_args@ | Arguments passed as is to the JVM. |
471
+ | @:format@ | Report format, either @:txt@ or @:xml@ |
472
+
473
+
474
+ Next, let's talk about "customizing your environment and using
475
+ profiles":settings_profiles.html