[DRE-commits] [ruby-aruba] 69/74: Cleanup README
Hideki Yamane
henrich at moszumanska.debian.org
Sat Nov 28 01:16:48 UTC 2015
This is an automated email from the git hooks/post-receive script.
henrich pushed a commit to branch debian/sid
in repository ruby-aruba.
commit 8260d90ab618ce752b00b49a4e5b82e51c8e9898
Author: Dennis Günnewig <dg1 at ratiodata.de>
Date: Fri Nov 27 11:40:01 2015 +0100
Cleanup README
---
README.md | 343 ++-------------------
features/api/filesystem/fixtures.feature | 104 +++++++
.../writing_good_feature_tests.feature | 38 +++
features/hooks/after/command.feature | 10 +
features/hooks/before/command.feature | 10 +
features/platforms/jruby.feature | 14 +
features/steps/command/in_process.feature | 11 +
features/steps/filesystem/fixture.feature | 20 --
features/steps/filesystem/fixtures.feature | 64 ++++
9 files changed, 283 insertions(+), 331 deletions(-)
diff --git a/README.md b/README.md
index ce96706..c4a5da5 100644
--- a/README.md
+++ b/README.md
@@ -82,325 +82,46 @@ well. One might want to use it together with `rspec`.
end
```
-## API
+### Minitest
-`aruba` provides a wonderful API to be used in your tests:
-
-* Creating files/directories
-* Deleting files/directories
-* Checking file size
-* Checking file existence/absence
-* ...
-
-A full documentation of the API can be found [here](http://www.rubydoc.info/github/cucumber/aruba/master/frames).
-
-## Configuration
-
-Aruba has some default behaviour that you can change if you need to.
-
-### Use a different working directory
-
-Per default Aruba will create a directory `tmp/aruba` where it performs its file operations.
-If you want to change this behaviour put this into your `features/support/env.rb`:
-
-```ruby
-Before do
- @dirs = ["somewhere/else"]
-end
-```
-
-### Modify the PATH
-
-Aruba will automatically add the `bin` directory of your project to the `PATH` environment variable for
-the duration of each Cucumber scenario. So if you're developing a Ruby gem with a binary command, you
-can test those commands as though the gem were already installed.
-
-If you need other directories to be added to the `PATH`, you can put the following in `features/support/env.rb`:
-
-```ruby
-Aruba.configure do |config|
- config.command_search_paths = config.command_search_paths << '/my/special/bin/path'
-end
-```
-
-### Increasing timeouts
-
-A process sometimes takes longer than expected to terminate, and Aruba will kill them off (and fail your scenario) if it is still alive after 3 seconds. If you need more time you can modify the timeout by assigning a different value to `#exit_timeout` in a `Aruba.configure` block:
-
-```ruby
-Aruba.configure do |config|
- config.exit_timeout = 5
-end
-```
-
-### Increasing IO wait time
-
-Running processes interactively can result in race conditions when Aruba executes an IO-related step
-but the interactive process has not yet flushed or read some content. To help prevent this Aruba waits
-before reading or writing to the process if it is still running. You can control the wait by setting
-`aruba.config.io_wait_timeout` to an appropriate value. This is particularly useful with tags:
-
-```ruby
-Before('@slow_process') do
- aruba.config.io_wait_timeout = 5
-end
-```
-
-### Tags
-
-Aruba defines several tags that you can put on on individual scenarios, or on a feature.
-
-#### Seeing more output with `@announce-*`
-
-To get more information on what Aruba is doing, use these tags:
-
-* `@announce-command` - See what command is run
-* `@announce-stdout` - See the stdout
-* `@announce-stderr` - See the stderr
-* `@announce-output` - See the output of stdout and stderr
-* `@announce-directory` - See the current directory
-* `@announce-environment` - See environment variables set by Aruba
-* `@announce` - Does all of the above
-
-### Adding Hooks
-
-You can hook into Aruba's lifecycle just before it runs a command and after it has run the command:
-
-```ruby
-Aruba.configure do |config|
- config.before :command do |cmd|
- puts "About to run '#{cmd}'"
- end
-
- config.after :command do |cmd|
- puts "After the run of '#{cmd}'"
- end
-end
-```
-
-#### Keep files around with `@no-clobber`
-
-Aruba clobbers all files in its working directory before each scenario. -Unless you tag it with `@no-clobber`
-
-#### Making assertions about ANSI escapes with `@ansi`
-
-Aruba strips away ANSI escapes from the stdout and stderr of spawned child processes by default. It's usually rather cumbersome to
-make assertions about coloured output. Still, there might be cases where you want to leave the ANSI escapes intact. Just tag your
-scenario with `@ansi`. Alternatively you can add your own Before
-hook that sets `@aruba_keep_ansi = true`.
-
-### Testing Ruby CLI programs without spawning a new Ruby process.
-
-If your CLI program is written in Ruby you can speed up your suite of scenarios by running
-your CLI in the same process as Cucumber/Aruba itself. In order to be able to do this, the
-entry point for your CLI application must be a class that has a constructor with a particular
-signature and an `execute!` method:
-
-```ruby
-class MyMain
- def initialize(argv, stdin=STDIN, stdout=STDOUT, stderr=STDERR, kernel=Kernel)
- @argv, @stdin, @stdout, @stderr, @kernel = argv, stdin, stdout, stderr, kernel
- end
-
- def execute!
- # your code here, assign a value to exitstatus
- @kernel.exit(exitstatus)
- end
-end
-```
-
-Your `bin/something` executable would look something like the following:
-
-```ruby
-require 'my_main'
-MyMain.new(ARGV.dup).execute!
-```
-
-Then wire it all up in your `features/support/env.rb` file:
-
-```ruby
-require 'aruba'
-require 'aruba/in_process'
+TBD :-)
-Aruba.process = Aruba::Processes::InProcess
-Aruba.process.main_class = MyMain
-```
-
-That's it! Everything will now run inside the same ruby process, making your suite
-a lot faster. Cucumber itself uses this approach to test itself, so check out the
-Cucumber source code for an example.
-
-*Pros*:
-
-* Very fast compared to spawning processes
-* You can use libraries like
- [simplecov](https://github.com/colszowka/simplecov) more easily, because
- there is only one "process" which adds data to `simplecov`'s database
-
-*Cons*:
-* You might oversee some bugs: You might forget to require libraries in your
- "production" code, because you have required them in your testing code
-
-### JRuby Tips
-
-Improve startup time by disabling JIT and forcing client JVM mode. This can be accomplished by adding
-
-```ruby
-require 'aruba/jruby'
-```
-
-or setting a hook like this example:
-
-```ruby
-Aruba.configure do |config|
- config.before :command do |cmd|
- set_env('JRUBY_OPTS', "-X-C #{ENV['JRUBY_OPTS']}") # disable JIT since these processes are so short lived
- set_env('JAVA_OPTS', "-d32 #{ENV['JAVA_OPTS']}") # force jRuby to use client JVM for faster startup times
- end
-end if RUBY_PLATFORM == 'java'
-```
-
-*Note* - no conflict resolution on the JAVA/JRuby environment options is
-done; only merging. For more complex settings please manually set the
-environment variables in the hook or externally.
+## Documentation
-A larger process timeout for java may be needed
+### User Documentation
-```ruby
-Before do
- @aruba_timeout_seconds = RUBY_PLATFORM == 'java' ? 60 : 10
-end
-```
-
-Refer to http://blog.headius.com/2010/03/jruby-startup-time-tips.html for other tips on startup time.
-
-## Fixtures
-
-Sometimes your tests need existing files to work - e.g binary data files you
-cannot create programmatically. Since `aruba` >= 0.6.3 includes some basic
-support for fixtures. All you need to do is the following:
-
-1. Create a `fixtures`-directory
-2. Create fixture files in this directory
-
-The `expand_path`-helper will expand `%` to the path of your fixtures
-directory:
-
-```ruby
-expand_path('%/song.mp3')
-# => /home/user/projects/my_project/fixtures/song.mp3
-```
-
-*Example*
-
-1. Create fixtures directory
+If you're interested in our steps and API, please browser our [feature
+files](https://github.com/cucumber/aruba/tree/master/features). You can find a
+lot of examples there. A good starting point are [Getting
+Started](https://github.com/cucumber/aruba/tree/master/features/getting_started)
+and [Step
+Overview](https://github.com/cucumber/aruba/blob/master/features/steps/overview.feature).
+A more or less full list of our steps can be found
+[here](https://github.com/cucumber/aruba/tree/master/features/steps). Our API
+is documentated
+[here](https://github.com/cucumber/aruba/tree/master/features/api) and some
+more information about how to configure `aruba`, can be found
+[here](https://github.com/cucumber/aruba/tree/master/features/configuration).
+The "RSpec" matchers provided by `aruba`, are documented
+[here](https://github.com/cucumber/aruba/tree/master/features/matchers).
- ```bash
- cd project
-
- mkdir -p fixtures/
- # or
- mkdir -p test/fixtures/
- # or
- mkdir -p spec/fixtures/
- # or
- mkdir -p features/fixtures/
- ```
-
-2. Store `song.mp3` in `fixtures`-directory
-
- ```bash
- cp song.mp3 fixtures/
- ```
+You can find our documentation on
+[Relish](http://www.relishapp.com/cucumber/aruba/docs) as well. Unfortunately
+"Relish" does not like the way we structered our feature tests. So this
+documentation found there may be not complete.
-3. Add fixture to vcs-repository - e.g. `git`, `mercurial`
+### Developer Documentation
-4. Create test
-
- ```ruby
- RSpec.describe 'My Feature' do
- describe '#read_music_file' do
- context 'when the file exists' do
- let(:path) { expand_path('%/song.mp3') }
-
- before :each do
- cd('.') { FileUtils.cp path, 'file.mp3' }
- end
-
- before :each do
- run 'my_command'
- end
-
- it { expect(all_stdout).to include('Rate is 128 KB') }
- end
- end
- end
- ```
-
-## Reporting
-
-*Important* - you need [Pygments](http://pygments.org/) installed to use this feature.
-
-Aruba can generate a HTML page for each scenario that contains:
-
-* The title of the scenario
-* The description from the scenario (You can use Markdown here)
-* The command(s) that were run
-* The output from those commands (in colour if the output uses ANSI escapes)
-* The files that were created (syntax highlighted in colour)
-
-In addition to this, it creates an `index.html` file with links to all individual report files.
-Reporting is off by default, but you can enable it by defining the `ARUBA_REPORT_DIR` environment variable, giving it the value
-where reports should be written:
-
- ARUBA_REPORT_DIR=doc cucumber features
-
-This will use Aruba's built-in template by default (See the `templates` folder). If you want to use your own template you can override its location:
-
- ARUBA_REPORT_TEMPLATES=templates ARUBA_REPORT_DIR=doc cucumber features
-
-The templates directory must contain a `main.erb` and `files.erb` template. It can also contain other assets such
-as css, javascript and images. All of these files will be copied over to the report dir well.
-
-### Escaping Markdown
-
-There are some edge cases where Gherkin and Markdown don't agree. Bullet lists using `*` is one example. The `*` is also an alias for
-step keywords in Gherkin. Markdown headers (the kind starting with a `#`) is another example. They are parsed as comments by Gherkin. To use either of these, just escape them with a backslash. So instead of writing:
-
-```gherkin
-Scenario: Make tea
- ## Making tea
- * Get a pot
- * And some hot water
-
- Given...
-```
-
-You'd write:
-
-```gherkin
-Scenario: Make tea
- \## Making tea
- \* Get a pot
- \* And some hot water
-
- Given...
-```
-
-This way Gherkin won't recognize these lines as special tokens, and the reporter will render them as Markdown. (The reporter strips
-away any leading the backslashes before handing it off to the Markdown parser).
-
-Another option is to use alternative Markdown syntax and omit conflicts and escaping altogether:
+`aruba` provides a wonderful API to be used in your tests:
-```gherkin
-Scenario: Make tea
- Making tea
- ----------
- - Get a pot
- - And some hot water
+* Creating files/directories
+* Deleting files/directories
+* Checking file size
+* Checking file existence/absence
+* ...
- Given...
-```
+A full documentation of the API can be found
+[here](http://www.rubydoc.info/github/cucumber/aruba/master/frames).
## Contributing
@@ -408,4 +129,4 @@ Please see the `CONTRIBUTING.md`.
## Copyright
-Copyright (c) 2010,2011,2012,2013,2014 Aslak Hellesøy, David Chelimsky and Mike Sassak. See LICENSE for details.
+Copyright (c) 2010-2015 Aslak Hellesøy et al. See LICENSE for details.
diff --git a/features/api/filesystem/fixtures.feature b/features/api/filesystem/fixtures.feature
new file mode 100644
index 0000000..96d0402
--- /dev/null
+++ b/features/api/filesystem/fixtures.feature
@@ -0,0 +1,104 @@
+Feature: Use fixtures in your tests
+
+ Sometimes your tests need existing files to work - e.g binary data files you
+ cannot create programmatically. Since `aruba` >= 0.6.3 includes some basic
+ support for fixtures. All you need to do is the following:
+
+ 1. Create a `fixtures`-directory
+ 2. Create fixture files in this directory
+
+
+ Background:
+ Given I use a fixture named "cli-app"
+
+ Scenario: Use a fixture for your tests
+ Given a file named "features/fixtures.feature" with:
+ """
+ Feature: Fixture
+ Scenario: Fixture
+ Given a file named "fixtures_spec.rb" with:
+ \"\"\"
+ RSpec.describe 'My Feature' do
+ describe '#read_music_file' do
+ context 'when the file exists' do
+ before :each { copy '%/song.mp3', 'file.mp3' }
+
+ it { expect('file.mp3').to be_an_existing_file }
+ end
+ end
+ end
+ \"\"\"
+ """
+ And a directory named "fixtures"
+ And an empty file named "fixtures/fixtures-app/test.txt"
+ When I run `rspec`
+ Then the specs should all pass
+
+ Scenario: Use a fixture for your tests in test/
+ Given a file named "features/fixtures.feature" with:
+ """
+ Feature: Fixture
+ Scenario: Fixture
+ Given a file named "fixtures_spec.rb" with:
+ \"\"\"
+ RSpec.describe 'My Feature' do
+ describe '#read_music_file' do
+ context 'when the file exists' do
+ before :each { copy '%/song.mp3', 'file.mp3' }
+
+ it { expect('file.mp3').to be_an_existing_file }
+ end
+ end
+ end
+ \"\"\"
+ """
+ And a directory named "test/fixtures"
+ And an empty file named "test/fixtures/fixtures-app/test.txt"
+ When I run `rspec`
+ Then the specs should all pass
+
+ Scenario: Use a fixture for your tests in spec/
+ Given a file named "features/fixtures.feature" with:
+ """
+ Feature: Fixture
+ Scenario: Fixture
+ Given a file named "fixtures_spec.rb" with:
+ \"\"\"
+ RSpec.describe 'My Feature' do
+ describe '#read_music_file' do
+ context 'when the file exists' do
+ before :each { copy '%/song.mp3', 'file.mp3' }
+
+ it { expect('file.mp3').to be_an_existing_file }
+ end
+ end
+ end
+ \"\"\"
+ """
+ And a directory named "spec/fixtures"
+ And an empty file named "spec/fixtures/fixtures-app/test.txt"
+ When I run `rspec`
+ Then the specs should all pass
+
+ Scenario: Use a fixture for your tests in features/
+ Given a file named "features/fixtures.feature" with:
+ """
+ Feature: Fixture
+ Scenario: Fixture
+ Given a file named "fixtures_spec.rb" with:
+ \"\"\"
+ RSpec.describe 'My Feature' do
+ describe '#read_music_file' do
+ context 'when the file exists' do
+ before :each { copy '%/song.mp3', 'file.mp3' }
+
+ it { expect('file.mp3').to be_an_existing_file }
+ end
+ end
+ end
+ \"\"\"
+ """
+ And a directory named "features/fixtures"
+ And an empty file named "features/fixtures/fixtures-app/test.txt"
+ When I run `rspec`
+ Then the specs should all pass
diff --git a/features/getting_started/writing_good_feature_tests.feature b/features/getting_started/writing_good_feature_tests.feature
new file mode 100644
index 0000000..3ee5eee
--- /dev/null
+++ b/features/getting_started/writing_good_feature_tests.feature
@@ -0,0 +1,38 @@
+Feature: Writing good feature tests with aruba to create documentations
+
+ You can use Markdown within your feature tests. This is quite good to write a
+ living documentation.
+
+ There are some edge cases where Gherkin and Markdown don't agree. Bullet lists
+ using `*` is one example. The `*` is also an alias for step keywords in
+ Gherkin. Markdown headers (the kind starting with a `#`) is another example.
+ They are parsed as comments by Gherkin. To use either of these, just escape
+ them with a backslash. Alternatively just use the "-".
+
+ You'd write:
+
+ ```gherkin
+ Scenario: Make tea
+ \## Making tea
+ \* Get a pot
+ \* And some hot water
+
+ Given...
+ ```
+
+ This way Gherkin won't recognize these lines as special tokens, and the
+ reporter will render them as Markdown. (The reporter strips away any leading
+ the backslashes before handing it off to the Markdown parser).
+
+ Another option is to use alternative Markdown syntax and omit conflicts and
+ escaping altogether:
+
+ ```gherkin
+ Scenario: Make tea
+ Making tea
+ ----------
+ - Get a pot
+ - And some hot water
+
+ Given...
+ ```
diff --git a/features/hooks/after/command.feature b/features/hooks/after/command.feature
index 8c7bb9f..290bb0e 100644
--- a/features/hooks/after/command.feature
+++ b/features/hooks/after/command.feature
@@ -3,6 +3,16 @@ Feature: After command hooks
You can configure Aruba to run blocks of code after it has run
a command. The command will be passed to the block.
+ You can hook into Aruba's lifecycle just before it runs a command and after it has run the command:
+
+ ```ruby
+ Aruba.configure do |config|
+ config.after :command do |cmd|
+ puts "After the run of '#{cmd}'"
+ end
+ end
+ ```
+
Background:
Given I use a fixture named "cli-app"
diff --git a/features/hooks/before/command.feature b/features/hooks/before/command.feature
index 91736d8..b11a03f 100644
--- a/features/hooks/before/command.feature
+++ b/features/hooks/before/command.feature
@@ -5,6 +5,16 @@ Feature: before_cmd hooks
The command will be passed to the block.
+ You can hook into Aruba's lifecycle just before it runs a command and after it has run the command:
+
+ ```ruby
+ Aruba.configure do |config|
+ config.before :command do |cmd|
+ puts "About to run '#{cmd}'"
+ end
+ end
+ ```
+
Background:
Given I use a fixture named "cli-app"
diff --git a/features/platforms/jruby.feature b/features/platforms/jruby.feature
new file mode 100644
index 0000000..d7e0fd0
--- /dev/null
+++ b/features/platforms/jruby.feature
@@ -0,0 +1,14 @@
+Feature: Support for JRuby
+
+ Improve startup time by disabling JIT and forcing client JVM mode. This can
+ be accomplished by adding
+
+ ```ruby
+ require 'aruba/jruby'
+ ```
+
+ *Note* - no conflict resolution on the JAVA/JRuby environment options is
+ done; only merging. For more complex settings please manually set the
+ environment variables in the hook or externally.
+
+ Refer to http://blog.headius.com/2010/03/jruby-startup-time-tips.html for other tips on startup time.
diff --git a/features/steps/command/in_process.feature b/features/steps/command/in_process.feature
index 8803581..b4c1022 100644
--- a/features/steps/command/in_process.feature
+++ b/features/steps/command/in_process.feature
@@ -34,6 +34,17 @@ Feature: Run commands in ruby process
and not during "loadtime", when the `ruby`-interpreter reads in you class
files.
+ *Pros*:
+ * Very fast compared to spawning processes
+ * You can use libraries like
+ [simplecov](https://github.com/colszowka/simplecov) more easily, because
+ there is only one "process" which adds data to `simplecov`'s database
+
+ *Cons*:
+ * You might oversee some bugs: You might forget to require libraries in your
+ "production" code, because you have required them in your testing code
+ * Using `:in_process` interactively is not supported
+
**WARNING**: Using `:in_process` interactively is not supported
Background:
diff --git a/features/steps/filesystem/fixture.feature b/features/steps/filesystem/fixture.feature
deleted file mode 100644
index f6cfa3c..0000000
--- a/features/steps/filesystem/fixture.feature
+++ /dev/null
@@ -1,20 +0,0 @@
-Feature: Use fixtures in your tests
-
- If you have more complicated requirements at your test setup, you can use
- fixtures with `aruba`.
-
- Background:
- Given I use a fixture named "cli-app"
-
- Scenario: Use a fixture for your tests
- Given a file named "features/fixtures.feature" with:
- """
- Feature: Fixture
- Scenario: Fixture
- Given I use a fixture named "fixtures-app"
- Then a file named "test.txt" should exist
- """
- And a directory named "fixtures"
- And an empty file named "fixtures/fixtures-app/test.txt"
- When I run `cucumber`
- Then the features should all pass
diff --git a/features/steps/filesystem/fixtures.feature b/features/steps/filesystem/fixtures.feature
new file mode 100644
index 0000000..4f71100
--- /dev/null
+++ b/features/steps/filesystem/fixtures.feature
@@ -0,0 +1,64 @@
+Feature: Use fixtures in your tests
+
+ Sometimes your tests need existing files to work - e.g binary data files you
+ cannot create programmatically. Since `aruba` >= 0.6.3 includes some basic
+ support for fixtures. All you need to do is the following:
+
+ 1. Create a `fixtures`-directory
+ 2. Create fixture files in this directory
+
+
+ Background:
+ Given I use a fixture named "cli-app"
+
+ Scenario: Use a fixture for your tests
+ Given a file named "features/fixtures.feature" with:
+ """
+ Feature: Fixture
+ Scenario: Fixture
+ Given I use a fixture named "fixtures-app"
+ Then a file named "test.txt" should exist
+ """
+ And a directory named "fixtures"
+ And an empty file named "fixtures/fixtures-app/test.txt"
+ When I run `cucumber`
+ Then the features should all pass
+
+ Scenario: Use a fixture for your tests in test/
+ Given a file named "features/fixtures.feature" with:
+ """
+ Feature: Fixture
+ Scenario: Fixture
+ Given I use a fixture named "fixtures-app"
+ Then a file named "test.txt" should exist
+ """
+ And a directory named "test/fixtures"
+ And an empty file named "test/fixtures/fixtures-app/test.txt"
+ When I run `cucumber`
+ Then the features should all pass
+
+ Scenario: Use a fixture for your tests in specs/
+ Given a file named "features/fixtures.feature" with:
+ """
+ Feature: Fixture
+ Scenario: Fixture
+ Given I use a fixture named "fixtures-app"
+ Then a file named "test.txt" should exist
+ """
+ And a directory named "spec/fixtures"
+ And an empty file named "spec/fixtures/fixtures-app/test.txt"
+ When I run `cucumber`
+ Then the features should all pass
+
+ Scenario: Use a fixture for your tests in features/
+ Given a file named "features/fixtures.feature" with:
+ """
+ Feature: Fixture
+ Scenario: Fixture
+ Given I use a fixture named "fixtures-app"
+ Then a file named "test.txt" should exist
+ """
+ And a directory named "features/fixtures"
+ And an empty file named "features/fixtures/fixtures-app/test.txt"
+ When I run `cucumber`
+ Then the features should all pass
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-ruby-extras/ruby-aruba.git
More information about the Pkg-ruby-extras-commits
mailing list