knapsack_pro 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e868eb591c4891dbb94e7af8911d82108b7f6eb5
-  data.tar.gz: 9bfad8c2e053b0e663a28d98be2e9f85becdbb69
+  metadata.gz: 298cd101879e3a4da08f66de0b2ccfe6fd4be478
+  data.tar.gz: a393fbb53dff07029ffcc4ffde88b7a99150f9aa
 SHA512:
-  metadata.gz: e9839f1c256278b9b55312ea428ec59465e9548686f69b2ff37a689ac9b787601179ad01a19b74e102704d39b929605d700eef0f941d5def183796605727d8d8
-  data.tar.gz: 4e78f4f8bb6ed5f944d53dd10e29425361c97875ae57b9a49f03982780733570113c5fdd748dedf57805e31e2c1478ec5ad9387ca06cdd68d1ff6ded7b4dca2e
+  metadata.gz: 67bb457b7c35e6c1135f197d34a67e0b4e222e9a8be9dd24a093b2761fdf497349c2b2cd95d5636333f6bb9aadb980ab56374b2b3d914e3457422be86cd5fe2d
+  data.tar.gz: 4bcc5069b5aa69d8be4f1477a332c0318a97f4d122493cd6c393196ea672831e921093ad402542a99018928f83d1dc5d59cd038b8dadf66ba2859c72c75effc2

data/.gitignore

@@ -27,9 +27,9 @@ build/
 
 # for a library or gem, you might want to ignore these files since the code is
 # intended to run in multiple environments; otherwise, check them in:
-# Gemfile.lock
-# .ruby-version
-# .ruby-gemset
+Gemfile.lock
+.ruby-version
+.ruby-gemset
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 * TODO
 
+### 0.1.0
+
+First working release on rubygems.org.
+
 ### 0.0.1
 
 Init repository.

data/README.md

@@ -5,15 +5,379 @@
 [![Code Climate](https://codeclimate.com/github/KnapsackPro/knapsack_pro-ruby/badges/gpa.svg)](https://codeclimate.com/github/KnapsackPro/knapsack_pro-ruby)
 [![Test Coverage](https://codeclimate.com/github/KnapsackPro/knapsack_pro-ruby/badges/coverage.svg)](https://codeclimate.com/github/KnapsackPro/knapsack_pro-ruby)
 
-Knapsack Pro gem splits tests across CI nodes and makes sure that tests will run comparable time on each node. It uses KnapsackPro.com API.
+Knapsack Pro gem splits tests across CI nodes and makes sure that tests will run comparable time on each node. It uses [KnapsackPro.com API](http://docs.knapsackpro.com). Original idea came from [knapsack](https://github.com/ArturT/knapsack) gem.
 
-The gem supports:
+The knapsack_pro gem supports:
 
 * [RSpec](http://rspec.info)
 * [Cucumber](https://cucumber.io)
 * [Minitest](http://docs.seattlerb.org/minitest/)
 * [Turnip](https://github.com/jnicklas/turnip)
 
-# Basic info
+__Would you like to try knapsack_pro gem?__ Drop me an [email](https://github.com/KnapsackPro/knapsack_pro-ruby/blob/master/knapsack_pro.gemspec#L10) so I will generate API keys for you.
 
-knapsack_pro gem is not ready yet. Please see https://github.com/ArturT/knapsack - it's working version you can use in your project for now.
+# How knapsack_pro works?
+
+## Basics
+
+Basically it will track your branches, commits and on 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
+
+For instance when you will run tests with rake knapsack_pro:rspec then:
+
+* information about all your existing test files are sent to API http://docs.knapsackpro.com/api/v1/#build_distributions_subset_post
+* API returns which files should be executed on particular CI node (example KNAPSACK_PRO_CI_NODE_INDEX=0)
+* when API server has info about previous tests runs then it will use it to return more accurate test split results, in other case API returns simple split based on directory names
+* knapsack_pro will run test files which got from API
+* after tests finished knapsack_pro will send information about time execution of each file to API http://docs.knapsackpro.com/api/v1/#build_subsets_post so data can be used for future test runs
+
+# Requirements
+
+* >= Ruby 2.0
+
+# Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Update gem](#update-gem)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [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)
+  - [Set API key token](#set-api-key-token)
+  - [Set knapsack_pro command to execute tests](#set-knapsack_pro-command-to-execute-tests)
+- [Extra configuration for CI server](#extra-configuration-for-ci-server)
+  - [Info about ENV variables](#info-about-env-variables)
+    - [Repository adapter](#repository-adapter)
+    - [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)
+  - [Knapsack Pro binary](#knapsack-pro-binary)
+  - [Supported CI providers](#supported-ci-providers)
+    - [Info for CircleCI users](#info-for-circleci-users)
+    - [Info for Travis users](#info-for-travis-users)
+    - [Info for semaphoreapp.com users](#info-for-semaphoreappcom-users)
+    - [Info for buildkite.com users](#info-for-buildkitecom-users)
+- [Gem tests](#gem-tests)
+  - [Spec](#spec)
+- [Contributing](#contributing)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Update gem
+
+Please check [changelog](CHANGELOG.md) before update gem. Knapsack Pro follows [semantic versioning](http://semver.org).
+
+## Installation
+
+Add those lines to your application's Gemfile:
+
+```ruby
+group :test, :development do
+  gem 'knapsack_pro'
+end
+```
+
+And then execute:
+
+    $ bundle
+
+
+Add this line at the bottom of `Rakefile` if your project has it:
+
+```ruby
+KnapsackPro.load_tasks if defined?(KnapsackPro)
+```
+
+## Usage
+
+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
+
+Add at the beginning of your `spec_helper.rb`:
+
+```ruby
+require 'knapsack_pro'
+
+# CUSTOM_CONFIG_GOES_HERE
+
+KnapsackPro::Adapters::RSpecAdapter.bind
+```
+
+### Step for Cucumber
+
+Create file `features/support/knapsack_pro.rb` and add there:
+
+```ruby
+require 'knapsack_pro'
+
+# CUSTOM_CONFIG_GOES_HERE
+
+KnapsackPro::Adapters::CucumberAdapter.bind
+```
+
+### Step for Minitest
+
+Add at the beginning of your `test_helper.rb`:
+
+```ruby
+require 'knapsack_pro'
+
+# CUSTOM_CONFIG_GOES_HERE
+
+knapsack_pro_adapter = KnapsackPro::Adapters::MinitestAdapter.bind
+knapsack_pro_adapter.set_test_helper_path(__FILE__)
+```
+
+### Custom configuration
+
+You can change default Knapsack Pro configuration for RSpec, Cucumber or Minitest tests. Here are examples what you can do. Put below configuration instead of `CUSTOM_CONFIG_GOES_HERE`.
+
+```ruby
+# you can use your own logger
+require 'logger'
+KnapsackPro.logger = Logger.new(STDOUT)
+KnapsackPro.logger.level = Logger::INFO
+```
+
+## Setup your CI server
+
+### Set API key token
+
+Set one or a few tokens depend on how many test suites you run on CI server.
+
+* `KNAPSACK_PRO_TEST_SUITE_TOKEN_RSPEC` - as value set token for rspec test suite. Token can be generated when you sign in to [knapsackpro.com](http://www.knapsackpro.com).
+* `KNAPSACK_PRO_TEST_SUITE_TOKEN_CUCUMBER` - token for cucumber test suite.
+* `KNAPSACK_PRO_TEST_SUITE_TOKEN_MINITEST` - token for minitest test suite.
+
+__Tip:__ In case you have for instance multiple rspec test suites then prepend each of knapsack_pro command which executes tests with `KNAPSACK_PRO_TEST_SUITE_TOKEN_RSPEC` variable.
+
+### Set knapsack_pro command to execute tests
+
+On your CI server run this command for the first CI node. Update `KNAPSACK_PRO_CI_NODE_INDEX` for the next one.
+
+    # Step for RSpec
+    $ KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 bundle exec rake knapsack_pro:rspec
+
+    # Step for Cucumber
+    $ KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 bundle exec rake knapsack_pro:cucumber
+
+    # Step for Minitest
+    $ KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 bundle exec rake knapsack_pro:minitest
+
+You can add `KNAPSACK_PRO_TEST_FILE_PATTERN` if your tests are not in default directory. For instance:
+
+    # Step for RSpec
+    $ KNAPSACK_PRO_TEST_FILE_PATTERN="directory_with_specs/**/*_spec.rb" KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 bundle exec rake knapsack_pro:rspec
+
+    # Step for Cucumber
+    $ 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
+
+## Extra configuration for CI server
+
+### Info about ENV variables
+
+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.
+
+`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`.
+
+#### Repository adapter
+
+`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, commit hash and project directory path.
+By default this variable has no value so knapsack_pro will try to get those info 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_BRANCH` - It's branch name. You run tests on this branch.
+
+`KNAPSACK_PRO_COMMIT_HASH` - Commit hash. You run tests for this commit.
+
+`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.
+
+#### 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).
+
+`KNAPSACK_PRO_MODE` - Default value is `production`. When mode is `development` then endpoint is `http://api.knapsackpro.dev:3000`. When mode is `test` then endpoint is `http://api-staging.knapsackpro.com`.
+
+### Passing arguments to rake task
+
+#### Passing arguments to rspec
+
+Knapsack Pro allows you to pass arguments through to rspec. For example if you want to run only specs that have the tag `focus`. If you do this with rspec directly it would look like:
+
+    $ bundle exec rake rspec --tag focus
+
+To do this with Knapsack Pro you simply add your rspec arguments as parameters to the knapsack_pro rake task.
+
+    $ bundle exec rake "knapsack_pro:rspec[--tag focus]"
+
+#### Passing arguments to cucumber
+
+Add arguments to knapsack_pro cucumber task like this:
+
+    $ bundle exec rake "knapsack_pro:cucumber[--name feature]"
+
+#### Passing arguments to minitest
+
+Add arguments to knapsack_pro minitest task like this:
+
+    $ bundle exec rake "knapsack_pro:minitest[--arg_name value]"
+
+For instance to run verbose tests:
+
+    $ bundle exec rake "knapsack_pro:minitest[--verbose]"
+
+### Knapsack Pro binary
+
+You can install knapsack_pro globally and use binary. For instance:
+
+    $ knapsack_pro rspec "--tag custom_tag_name --profile"
+    $ knapsack_pro cucumber "--name feature"
+    $ knapsack_pro minitest "--verbose --pride"
+
+This is optional way of using knapsack_pro when you don't want to add it to `Gemfile`.
+
+### Supported CI providers
+
+#### Info for CircleCI users
+
+If you are using circleci.com you can omit `KNAPSACK_PRO_CI_NODE_TOTAL` and `KNAPSACK_PRO_CI_NODE_INDEX`. Knapsack Pro will use `KNAPSACK_PRO_CIRCLE_NODE_TOTAL` and `KNAPSACK_PRO_CIRCLE_NODE_INDEX` provided by CircleCI.
+
+Here is an example for test configuration in your `circleci.yml` file.
+
+```yaml
+test:
+  override:
+    # Step for RSpec
+    - bundle exec rake knapsack_pro:rspec:
+        parallel: true # Caution: there are 8 spaces indentation!
+
+    # Step for Cucumber
+    - bundle exec rake knapsack_pro:cucumber:
+        parallel: true # Caution: there are 8 spaces indentation!
+
+    # Step for Minitest
+    - bundle exec rake knapsack_pro:minitest:
+        parallel: true # Caution: there are 8 spaces indentation!
+```
+
+Please remember to add additional containers for your project in CircleCI settings.
+
+#### Info for Travis users
+
+You can parallel your builds across virtual machines with [travis matrix feature](http://docs.travis-ci.com/user/speeding-up-the-build/#Parallelizing-your-builds-across-virtual-machines). Edit `.travis.yml`
+
+```yaml
+script:
+  # Step for RSpec
+  - "bundle exec rake knapsack_pro:rspec"
+
+  # Step for Cucumber
+  - "bundle exec rake knapsack_pro:cucumber"
+
+  # Step for Minitest
+  - "bundle exec rake knapsack_pro:minitest"
+
+env:
+  - KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0
+  - KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=1
+```
+
+If you want to have some global ENVs and matrix of ENVs then do it like this:
+
+```yaml
+script:
+  # Step for RSpec
+  - "bundle exec rake knapsack_pro:rspec"
+
+  # Step for Cucumber
+  - "bundle exec rake knapsack_pro:cucumber"
+
+  # Step for Minitest
+  - "bundle exec rake knapsack_pro:minitest"
+
+env:
+  global:
+    - RAILS_ENV=test
+    - MY_GLOBAL_VAR=123
+    - KNAPSACK_PRO_CI_NODE_TOTAL=2
+  matrix:
+    - KNAPSACK_PRO_CI_NODE_INDEX=0
+    - KNAPSACK_PRO_CI_NODE_INDEX=1
+```
+
+Such configuration will generate matrix with 2 following ENV rows:
+
+    KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 RAILS_ENV=test MY_GLOBAL_VAR=123
+    KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=1 RAILS_ENV=test MY_GLOBAL_VAR=123
+
+More info about global and matrix ENV configuration in [travis docs](http://docs.travis-ci.com/user/build-configuration/#Environment-variables).
+
+#### Info for semaphoreapp.com users
+
+Knapsack Pro supports semaphoreapp ENVs `SEMAPHORE_THREAD_COUNT` and `SEMAPHORE_CURRENT_THREAD`. The only thing you need to do is set up knapsack_pro rspec/cucumber/minitest command for as many threads as you need. Here is an example:
+
+    # Thread 1
+    ## Step for RSpec
+    bundle exec rake knapsack_pro:rspec
+    ## Step for Cucumber
+    bundle exec rake knapsack_pro:cucumber
+    ## Step for Minitest
+    bundle exec rake knapsack_pro:minitest
+
+    # Thread 2
+    ## Step for RSpec
+    bundle exec rake knapsack_pro:rspec
+    ## Step for Cucumber
+    bundle exec rake knapsack_pro:cucumber
+    ## Step for Minitest
+    bundle exec rake knapsack_pro:minitest
+
+Tests will be split across threads.
+
+#### Info for buildkite.com users
+
+Knapsack Pro supports buildkite ENVs `BUILDKITE_PARALLEL_JOB_COUNT` and `BUILDKITE_PARALLEL_JOB`. The only thing you need to do is to configure the parallelism parameter in your build step and run the appropiate command in your build
+
+    # Step for RSpec
+    bundle exec rake knapsack_pro:rspec
+
+    # Step for Cucumber
+    bundle exec rake knapsack_pro:cucumber
+
+    # Step for Minitest
+    bundle exec rake knapsack_pro:minitest
+
+## Gem tests
+
+### Spec
+
+To run specs for Knapsack Pro gem type:
+
+    $ bundle exec rspec spec
+
+## Contributing
+
+1. Fork it ( https://github.com/ArturT/knapsack/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/bin/knapsack_pro

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/knapsack_pro'
+
+runner = ARGV[0]
+arguments = ARGV[1]
+
+MAP = {
+  'rspec' => KnapsackPro::Runners::RSpecRunner,
+  'cucumber' => KnapsackPro::Runners::CucumberRunner,
+  'minitest' => KnapsackPro::Runners::MinitestRunner,
+}
+
+runner_class = MAP[runner]
+
+if runner_class
+  runner_class.run(arguments)
+else
+  raise 'Undefined runner. Please provide runner name and optional arguments, for instance: knapsack_pro rspec "--color --profile"'
+end

data/circle.yml

@@ -1,3 +1,5 @@
 machine:
+  ruby:
+    version: 2.2.3
   environment:
     CODECLIMATE_REPO_TOKEN: b6626e682a8e97e0c5978febc92c3526792a2d018b41b8e1b52689da37fb7d92