README.md in heroku_hatchet-1.0.0 vs README.md in heroku_hatchet-1.1.0

- old
+ new

@@ -77,11 +77,11 @@ ``` Now in your test you can reference one of these applications by using it's git name: ```ruby -Hatchet::AnvilApp.new('no_lockfile') +Hatchet::Runner.new('no_lockfile') ``` If you have conflicting names, use full paths. A word of warning on including repos inside of your test @@ -97,42 +97,62 @@ A note on external repos: since you're basing tests on these repos, it is in your best interest to not change them or your tests may spontaneously fail. In the future we may create a hatchet.lockfile or something to declare the commit + +## Deployments: Anvil vs. Git + +Before you start testing a buildpack, understand that there are two different ways to deploy to Heroku. The first you are likely familiar with Git, requires a `git push heroku master`. You can configure the buildpack of an app being deployed in this way through the `BUILDPACK_URL` environment variable of the app. The buildpack url must be publicaly available. + +The second method is by [Anvil](https://github.com/ddollar/anvil-cli) . In this method the build is performed as a service. This service takes an app to be built as well as a buildpack. When using Anvil, you do not need to put your buildpack anywhere publicly available. + +When developing local features you will likely wish to use Anvil since it does not require a publicly available URL and you can iterate faster. When testing for regression you will almost always want to use Git, since it is the closest approximation to real world deployment. For this reason Hatchet provides a globally configurable way to toggle between the two deployment modes `Hatchet::Runner` + + ## Deploying apps -Now that you've got your apps locally you can have hatchet deploy them for you. Hatchet can deploy using one of two ways Anvil and Git. A `Hatchet::AnvilApp` will deploy using Anvil against the current directory. This means that the buildpack you have locally will be used when deploying, due to this we recommend using Anvil to run your tests. +Now that you've got your apps locally you can have hatchet deploy them for you. Hatchet can deploy using one of two ways Anvil and Git. To specify one or the other set your `HATCHET_DEPLOY_STRATEGY` environment variable to `anvil` or `git`. The default is `anvil`. In production, you should always test against `git` -A `Hatchet::GitApp` will deploy using the standard `git push heroku master`, if you use this option you need to have a publicly accessible copy of your buildpack. Using Git to test your buildpack may be slow and require you to frequently push your buildpack to a public git repo. For this reason we recommend using Anvil to run your tests: +A `Hatchet::GitApp` will deploy using the standard `git push heroku master` and is not configurable, if you use this option you need to have a publicly accessible copy of your buildpack. Using Git to test your buildpack may be slow and require you to frequently push your buildpack to a public git repo. For this reason we recommend using Anvil to run your tests locally: + ```ruby -Hatchet::AnvilApp.new("rails3_mri_193").deploy do |app| +Hatchet::Runner.new("rails3_mri_193").deploy do |app| end ``` +If you are using GIT, you can specify the location of your public buildpack url in an environment variable: + +```sh +HATCHET_BUILDPACK_BASE=https://github.com/heroku/heroku-buildpack-ruby.git +HATCHET_BUILDPACK_BRANCH=master +``` + +If you do not specify `HATCHET_BUILDPACK_URL` the default Ruby buildpack will be used. If you do not specify a `HATCHET_BUILDPACK_BRANCH` the current branch you are on will be used. + Deploys are expected to work, if the `ENV['HATCHET_RETRIES']` is set, then deploys will be automatically retried that number of times. Due to testing using a network and random Anvil failures, setting this value to `3` retries seems to work well. If an app cannot be deployed within its allotted number of retries an error will be raised. If you are testing an app that is supposed to fail deployment you can set the `allow_failure: true` flag when creating the app: ```ruby -Hatchet::AnvilApp.new("no_lockfile", allow_failure: true).deploy do |app| +Hatchet::Runner.new("no_lockfile", allow_failure: true).deploy do |app| ``` After the block finishes your app will be removed from heroku. If you are investigating a deploy, you can add the `debug: true` flag to your app: ```ruby -Hatchet::AnvilApp.new("rails3_mri_193", debug: true).deploy do |app| +Hatchet::Runner.new("rails3_mri_193", debug: true).deploy do |app| ``` Now after Hatchet is done deploying your app it will remain on Heroku. It will also output the name of the app into your test logs so that you can `heroku run bash` into it for detailed postmortem. If you are wanting to run a test against a specific app without deploying to it, you can set the app name like this: ```ruby -app = Hatchet::AnvilApp.new("rails3_mri_193", name: "testapp") +app = Hatchet::Runner.new("rails3_mri_193", name: "testapp") ``` Deploying the app takes a few minutes, so you may want to skip that part to make debugging a problem easier since you're iterating much faster. @@ -141,11 +161,11 @@ ```ruby buildpack_path = File.expand_path 'test/fixtures/buildpacks/heroku-buildpack-ruby' def test_deploy - Hatchet::AnvilApp.new("rails3_mri_193", buildpack: buildpack_path).deploy do |app| + Hatchet::GitApp.new("rails3_mri_193", buildpack: buildpack_path).deploy do |app| # ... ``` If you are using a `Hatchet::GitApp` this is where you specify the publicly avaialble location of your buildpack, such as `https://github.com/heroku/heroku-buildpack-ruby.git#mybranch` @@ -153,19 +173,19 @@ ## Getting Deploy Output After Hatchet deploys your app you can get the output by using `app.output` ```ruby -Hatchet::AnvilApp.new("rails3_mri_193").deploy do |app| +Hatchet::Runner.new("rails3_mri_193").deploy do |app| puts app.output end ``` If you told Hatchet to `allow_failure: true` then the full output of the failed build will be in `app.output` even though the app was not deployed. It is a good idea to test against the output for text that should be present. Using a testing framework such as `Test::Unit` a failed test output may look like this ```ruby -Hatchet::AnvilApp.new("no_lockfile", allow_failure: true).deploy do |app| +Hatchet::Runner.new("no_lockfile", allow_failure: true).deploy do |app| assert_match "Gemfile.lock required", app.output end ``` Since an error will be raised on failed deploys you don't need to check for a deployed status (the error will automatically fail the test for you). @@ -173,29 +193,29 @@ ## Running Processes Often times asserting output of a build can only get you so far, and you will need to actually run a task on the dyno. To run a non-interactive command such as `heroku run ls` you can do this using the `app.run()` command and do not pass it a block ```ruby -Hatchet::AnvilApp.new("rails3_mri_193").deploy do |app| +Hatchet::Runner.new("rails3_mri_193").deploy do |app| assert_match "applications.css", app.run("ls public/assets") ``` This is useful for checking the existence of generated files such as assets. If you need to run an interactive session such as `heroku run bash` or `heroku run rails console` you can use the run command and pass a block: ```ruby -Hatchet::AnvilApp.new("rails3_mri_193").deploy do |app| +Hatchet::Runner.new("rails3_mri_193").deploy do |app| app.run("bash") do |bash| bash.run("ls") {|result| assert_match "Gemfile.lock", result } bash.run("cat Procfile") {|result| assert_match "web:", result } end end ``` or ```ruby -Hatchet::AnvilApp.new("rails3_mri_193").deploy do |app| +Hatchet::Runner.new("rails3_mri_193").deploy do |app| app.run("rails console") do |console| console.run("a = 1 + 2") {|result| assert_match "3", result } console.run("'foo' * a") {|result| assert_match "foofoofoo", result } end end @@ -225,10 +245,12 @@ ## Testing on Travis Once you've got your tests working locally, you'll likely want to get them running on Travis because a) CI is awesome, and b) you can use pull requests to run your all your tests in parallel without having to kill your network connection. +You will want to set the `HATCHET_DEPLOY_STRATEGY` to `git`. + To run on travis you will need to configure your `.travis.yml` to run the appropriate commands and to set up encrypted data so you can run tests against a valid heroku user. For reference see the `.travis.yml` from [hatchet](https://github.com/heroku/hatchet/blob/master/.travis.yml) and the [heroku-ruby-buildpack](https://github.com/heroku/heroku-buildpack-ruby/blob/master/.travis.yml). To make running on travis easier there is a rake task in Hatchet that can be run before your tests are executed ``` @@ -256,7 +278,10 @@ the command by going to the source code directory and running: $ ./bin/hatchet --help +## License + +MIT