README.md in knapsack_pro-0.5.0 vs README.md in knapsack_pro-0.6.0

- old
+ new

@@ -12,17 +12,17 @@ * [RSpec](http://rspec.info) * [Cucumber](https://cucumber.io) * [Minitest](http://docs.seattlerb.org/minitest/) * [Turnip](https://github.com/jnicklas/turnip) -__Would you like to try knapsack_pro gem?__ Please fill the [sign up form](https://docs.google.com/forms/d/1S8b5I-W2wr4_8C0tKu9AiW9y_5vq3SW9j2MMUql-hjE/viewform?c=0&w=1&hl=en). +__Would you like to try knapsack_pro gem?__ You can [get API token here](http://knapsackpro.com). # How knapsack_pro works? ## Basics -Basically it will track your branches, commits and on how many CI nodes you are running tests. +Basically it will track your branches, commits and for how many CI nodes you are running tests. Collected data about test time execution will be send to API where test suite split is done. Next time when you will run tests you will get proper test files for each CI node in order to achieve comparable time execution on each CI node. ## Details @@ -45,23 +45,23 @@ **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - [Update gem](#update-gem) - [Installation](#installation) - [How to set up](#how-to-set-up) - - [Usage](#usage) + - [Usage (How to set up 1 of 3)](#usage-how-to-set-up-1-of-3) - [Step for RSpec](#step-for-rspec) - [Step for Cucumber](#step-for-cucumber) - [Step for Minitest](#step-for-minitest) - [Custom configuration](#custom-configuration) - - [Setup your CI server](#setup-your-ci-server) + - [Setup your CI server (How to set up 2 of 3)](#setup-your-ci-server-how-to-set-up-2-of-3) - [Set API key token](#set-api-key-token) - [Set knapsack_pro command to execute tests](#set-knapsack_pro-command-to-execute-tests) + - [Repository adapter (How to set up 3 of 3)](#repository-adapter-how-to-set-up-3-of-3) + - [When you NOT set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER` (default)](#when-you-not-set-global-variable-knapsack_pro_repository_adapter-default) + - [When you set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER=git` (required when CI provider is not supported)](#when-you-set-global-variable-knapsack_pro_repository_adaptergit-required-when-ci-provider-is-not-supported) - [Extra configuration for CI server](#extra-configuration-for-ci-server) - [Info about ENV variables](#info-about-env-variables) - - [Repository adapter](#repository-adapter) - - [When you set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER=git` (optional)](#when-you-set-global-variable-knapsack_pro_repository_adaptergit-optional) - - [When you NOT set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER` (default)](#when-you-not-set-global-variable-knapsack_pro_repository_adapter-default) - [Environment variables for debugging gem](#environment-variables-for-debugging-gem) - [Passing arguments to rake task](#passing-arguments-to-rake-task) - [Passing arguments to rspec](#passing-arguments-to-rspec) - [Passing arguments to cucumber](#passing-arguments-to-cucumber) - [Passing arguments to minitest](#passing-arguments-to-minitest) @@ -101,15 +101,23 @@ ```ruby KnapsackPro.load_tasks if defined?(KnapsackPro) ``` +If you are using [VCR gem](https://github.com/vcr/vcr) then add Knapsack Pro API subdomain to [ignore hosts](https://www.relishapp.com/vcr/vcr/v/2-9-3/docs/configuration/ignore-request): + +```ruby +VCR.configure do |config| + config.ignore_hosts 'localhost', '127.0.0.1', '0.0.0.0', 'api.knapsackpro.com' +end +``` + ## How to set up -### Usage +### Usage (How to set up 1 of 3) -You can find here example of rails app with already configured knapsack_pro. +__Tip:__ You can find here example of rails app with already configured knapsack_pro. https://github.com/KnapsackPro/rails-app-with-knapsack_pro #### Step for RSpec @@ -157,11 +165,11 @@ require 'logger' KnapsackPro.logger = Logger.new(STDOUT) KnapsackPro.logger.level = Logger::INFO ``` -### Setup your CI server +### Setup your CI server (How to set up 2 of 3) #### Set API key token Set one or a few tokens depend on how many test suites you run on CI server. @@ -193,37 +201,41 @@ $ KNAPSACK_PRO_TEST_FILE_PATTERN="directory_with_features/**{,/*/**}/*.feature" KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 bundle exec rake knapsack_pro:cucumber # Step for Minitest $ KNAPSACK_PRO_TEST_FILE_PATTERN="directory_with_tests/**{,/*/**}/*_test.rb" KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 bundle exec rake knapsack_pro:minitest -__Tip:__ If you are using one of supported CI providers then instead of above steps you should [take a look on this](#supported-ci-providers). +__Tip:__ If you use one of supported CI providers then instead of above steps you should [take a look on this](#supported-ci-providers). -## Extra configuration for CI server +__Tip 2:__ If you use one of unsupported CI providers ([here is list of supported CI providers](#supported-ci-providers)) then you should [set KNAPSACK_PRO_REPOSITORY_ADAPTER=git](#when-you-set-global-variable-knapsack_pro_repository_adaptergit-required-when-ci-provider-is-not-supported). -### Info about ENV variables +### Repository adapter (How to set up 3 of 3) -By default knapsack_pro gem [supports a few CI providers](#supported-ci-providers) so you don't need to set environment variables. -In case when you use other CI provider for instance [Jenkins](https://jenkins-ci.org) etc then you need to provide configuration via below environment variables. +#### When you NOT set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER` (default) -`KNAPSACK_PRO_CI_NODE_TOTAL` - total number CI nodes you have. +By default `KNAPSACK_PRO_REPOSITORY_ADAPTER` variable has no value so knapsack_pro will try to get info about branch name and commit hash from [supported CI](#supported-ci-providers) (CI providers have branch, commit, project directory stored as environment variables). In case when you use other CI provider like Jenkins then please set below variables on your own. -`KNAPSACK_PRO_CI_NODE_INDEX` - index of current CI node starts from 0. Second CI node should have `KNAPSACK_PRO_CI_NODE_INDEX=1`. +`KNAPSACK_PRO_BRANCH` - It's branch name. You run tests on this branch. -#### Repository adapter +`KNAPSACK_PRO_COMMIT_HASH` - Commit hash. You run tests for this commit. -##### When you set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER=git` (optional) +You can also use git as repository adapter to determine branch and commit hash, please see below section. +#### When you set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER=git` (required when CI provider is not supported) + `KNAPSACK_PRO_REPOSITORY_ADAPTER` - When it has value `git` then your local version of git on CI server will be used to get info about branch name and commit hash. You need to set also `KNAPSACK_PRO_PROJECT_DIR` with project directory path. `KNAPSACK_PRO_PROJECT_DIR` - Path to the project on CI node for instance `/home/ubuntu/my-app-repository`. It should be main directory of your repository. -##### When you NOT set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER` (default) +## Extra configuration for CI server -By default `KNAPSACK_PRO_REPOSITORY_ADAPTER` variable has no value so knapsack_pro will try to get info about branch name and commit hash from [supported CI](#supported-ci-providers) (CI providers have branch, commit, project directory stored as environment variables). In case when you use other CI provider like Jenkins then please set below variables on your own. +### Info about ENV variables -`KNAPSACK_PRO_BRANCH` - It's branch name. You run tests on this branch. +By default knapsack_pro gem [supports a few CI providers](#supported-ci-providers) so you don't need to set some environment variables. +In case when you use other CI provider for instance [Jenkins](https://jenkins-ci.org) etc then you need to provide configuration via below environment variables. -`KNAPSACK_PRO_COMMIT_HASH` - Commit hash. You run tests for this commit. +`KNAPSACK_PRO_CI_NODE_TOTAL` - total number CI nodes you have. + +`KNAPSACK_PRO_CI_NODE_INDEX` - index of current CI node starts from 0. Second CI node should have `KNAPSACK_PRO_CI_NODE_INDEX=1`. #### Environment variables for debugging gem `KNAPSACK_PRO_ENDPOINT` - Default value is `http://api.knapsackpro.com` which is endpoint for [Knapsack Pro API](http://docs.knapsackpro.com).