Permalink
Browse files

updated readme

  • Loading branch information...
zilkey committed Apr 6, 2009
1 parent 588115e commit 0ff8d9bb43cdbd75ef55de25d4fcca6285bb15b1
Showing with 29 additions and 11 deletions.
  1. +29 −11 README.md
View
@@ -1,4 +1,4 @@
-In this post, I'll show you how to set up end-to-end capistrano testing using Cucumber. I've extracted this from the cucumber features I wrote for a gem I'm building named [auto_tagger](http://github.com/zilkey/auto_tagger/tree/master). To fully test capistrano recipes, your tests will have to:
+In this post, I'll show you how to set up end-to-end [Capistrano](http://www.capify.org/) testing using [Cucumber](http://cukes.info/). I've extracted this from the cucumber features I wrote for a gem I'm building named [auto_tagger](http://github.com/zilkey/auto_tagger/tree/master). To fully test capistrano recipes, your tests will have to:
* Create a local git repository
* Create a local app with a config/deploy.rb file
@@ -7,9 +7,19 @@ In this post, I'll show you how to set up end-to-end capistrano testing using Cu
* Run a `cap deploy` from the app (which will deploy to your test directory)
* Assert against the content of the deployed app in the test directory
-NOTE: this only will not work on Windows
+## Background - Capistrano recipes are almost never tested
+
+Looking around online, I couldn't find a single list of capistrano packages that has an automated test suite, even ones from some [big](http://github.com/engineyard/eycap/blob/81167b4c77b36434d7c35cebe55504cd939a4e5e/test/test_eycap.rb) [hosts](http://github.com/railsmachine/railsmachine/tree/master). It's no surprise that Capistrano tasks are seldom tested - testing capistrano recipes is hard, and even when you do test them, there are still so many variables in real-life deploys that you can't account for everything.
+
+It's like Rummy said:
+
+ > There are known knowns. There are things we know that we know. There are known unknowns. That is to say, there are things that we now know we don’t know. But there are also unknown unknowns. There are things we do not know we don’t know.
+
+ > from [wikipedia](http://en.wikipedia.org/wiki/Known_unknown)
+
+However, there are some things you can do to stave off the "known unknowns". For example, you know that someone might forget to set an important variable in their cap task and you know they might be using [cap-ext-multistage](http://weblog.jamisbuck.org/2007/7/23/capistrano-multistage). For these kinds of examples, Capistrano testing can give you much more assurance that a bug in your recipe is less likely to `rm -rf /*` on your remote machine.
-## Setup your keys
+## Getting started: setup your keys
To make life easy, you'll want to be able to ssh to your own machine. To do this, you'll need to create a key, then add that key to your authorized keys. If you don't already have a key setup locally, check out the excellent [RailsMachine guide](https://support.railsmachine.com/index.php?pg=kb.page&id=33). Once you have a key, you can copy it to authorized keys like so:
@@ -19,6 +29,10 @@ Now you should be able to ssh to your own box without entering a password. To l
If you are a Mac user you'll have to enable "Remote Access" from System Preferences to be able to ssh in to your own box. For security, only allow yourself to log in via ssh. The system preferences pane will show you the IP address you can use to ssh into.
+![Mac Remote Login Preference Pane](http://assets.pivotallabs.com/309/original/remote_login.png "Mac Remote Login Preference Pane")
+
+NOTE: this only will not work on Windows
+
## Setup your cucumber file system
The file system I'll use for this demo will look like this:
@@ -144,26 +158,30 @@ To make this pass, add a recipe like this:
## Debugging
-You'll notice that when you run `cucumber features` you get all of the output from capistrano. This makes your feature steps messy, but provides a lot of valuable debug information. If you want to silence it, you can use any number of tools, including piping the output to logs, or using `silence_stream`.
+You'll notice that when you run `cucumber features` you get all of the output from capistrano. This makes your output messy, but provides a lot of valuable debug information. If you want to silence it, you can use any number of tools, including piping the output to logs, or using methods like `silence_stream`.
-You'll also notice that the setup described above leaves the files in the `test_files` directory intact after each feature. This makes it easy to inspect the file system manually after each run - you can even `cd` into the `test_files/app` directory and re-run deployments, or tweak the `config/deploy.rb` file and re-deploy and then move your changes back to `templates/deploy.erb `.
+You'll also notice that the setup described above leaves the files in the `test_files` directory intact after each feature (it wipes it clean before each feature). This makes it easy to inspect the file system manually after each run. While developing, you can even `cd` into the `test_files/app` directory and re-run deployments, or tweak the `config/deploy.rb` file and re-deploy and then move your changes back to `templates/deploy.erb `.
## Next Steps
-This is just a quick sample to show you what you can do. You'll probably want to create a helper class of some sort to wrap up the file system calls, so your steps would look more like:
+This is just a quick sample to show you what you can do. It is not meant to be a good example of how to use cucumber (it has lots of instance variables, hard to read steps that are not reusable etc...), but rather a quick example of how to use cucumber to test cap recipes.
+
+You'll probably want to create a helper class of some sort to wrap up the file system calls, so your steps would look more like:
Given /^a an app$/ do
- FileHelper.create_repo
- FileHelper.create_app
- FileHelper.capify_app
+ MyFileHelper.create_repo
+ MyFileHelper.create_app
+ MyFileHelper.capify_app
end
## Testing against non-local environments
-You could in theory use this to test against any environment you have access to - just change the host in `templates/deploy.erb`. If you choose to test against a true remote machine, you'll have to figure out how to shell out commands to it. If you are on a mac, one thing that might help is to [mount a remote machine over ssh](http://lifehacker.com/software/ssh/geek-to-live--mount-a-file-system-on-your-mac-over-ssh-246129.php).
+You could in theory use this to test against any environment you have access to - just change the host in `templates/deploy.erb`. If you choose to test against a true remote machine, you'll have to figure out how to shell out commands to it.
+
+If you are on a mac, one thing that might help is to [mount a remote machine over ssh](http://lifehacker.com/software/ssh/geek-to-live--mount-a-file-system-on-your-mac-over-ssh-246129.php).
## Grab the source
The full source code for this app can be found at:
-[]()
+[http://github.com/zilkey/testing-capistrano-demo/tree/master](http://github.com/zilkey/testing-capistrano-demo/tree/master)

0 comments on commit 0ff8d9b

Please sign in to comment.