README.md in knapsack_pro-0.10.0 vs README.md in knapsack_pro-0.11.0

- old
+ new

@@ -74,16 +74,21 @@ - [Passing arguments to rspec](#passing-arguments-to-rspec) - [Passing arguments to cucumber](#passing-arguments-to-cucumber) - [Passing arguments to minitest](#passing-arguments-to-minitest) - [Passing arguments to spinach](#passing-arguments-to-spinach) - [Knapsack Pro binary](#knapsack-pro-binary) + - [Test file names encryption](#test-file-names-encryption) + - [How to enable test file names encryption?](#how-to-enable-test-file-names-encryption) + - [How to debug test file names?](#how-to-debug-test-file-names) - [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) - [Info for snap-ci.com users](#info-for-snap-cicom-users) +- [FAQ](#faq) + - [How to run tests for particular CI node in your development environment](#how-to-run-tests-for-particular-ci-node-in-your-development-environment) - [Gem tests](#gem-tests) - [Spec](#spec) - [Contributing](#contributing) <!-- END doctoc generated TOC please keep comment here to allow auto update --> @@ -293,16 +298,16 @@ Don't disable fixed test suite split when: * you expect to run the same subset of test suite multiple times for the same node (for instance your would like to retry only single CI node that failed) - Example of issue: https://github.com/KnapsackPro/knapsack_pro-ruby/issues/15 + Example of issue: + * https://github.com/KnapsackPro/knapsack_pro-ruby/issues/15 + * https://github.com/KnapsackPro/knapsack_pro-ruby/issues/12 * you start your tests not at the same time across your CI nodes. For instance, one of the CI node finished faster than the other CI node started. This would change the seed for the second CI node that started later. - Example of issue: https://github.com/KnapsackPro/knapsack_pro-ruby/issues/12 - #### 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`. @@ -350,10 +355,38 @@ $ knapsack_pro minitest "--verbose --pride" $ knapsack_pro spinach "--arg_name value" This is optional way of using knapsack_pro when you don't want to add it to `Gemfile`. +### Test file names encryption + +knapsack_pro gem collects information about you test file names and time execution. Those data are stored on KnapsackPro.com server. +If your test file names are sensitive data then you can encrypt the names before sending them to KnapsackPro.com API. + +By default, encryption is disabled because knapsack_pro can use your test files names to prepare better test suite split when the time execution data are not yet collected on KnapsackPro.com server. +When you will enable test file names encryption then your first test suite split may be less optimal than it could be. + +Each test file name is generated with `Digest::SHA2.hexdigest` method and 64 chars salt. + +#### How to enable test file names encryption? + +First you need to add environment variable `KNAPSACK_PRO_TEST_FILES_ENCRYPTED=true` to your CI server. + +Next step is to generate salt which will be used to encrypt test file names. + + $ bundle exec rake knapsack_pro:salt + +Add to your CI server generated environment variable `KNAPSACK_PRO_SALT`. + +#### How to debug test file names? + +If you need to check what is the encryption hash for particular test file your can check that with the rake task: + + $ KNAPSACK_PRO_SALT=xxx bundle exec rake knapsack_pro:encrypted_test_file_names[rspec] + +You can pass the name of test runner like rspec, minitest, cucumber, spinach as argument to rake task. + ### 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 `CIRCLE_NODE_TOTAL` and `CIRCLE_NODE_INDEX` provided by CircleCI. @@ -489,9 +522,25 @@ # Step for Spinach bundle exec rake knapsack_pro:spinach Please remember to set up token like `KNAPSACK_PRO_TEST_SUITE_TOKEN_RSPEC` as global environment. + +## FAQ + +### How to run tests for particular CI node in your development environment + +In your development environment you can debug tests that were run on the particular CI node. +For instance to run subset of tests for the first CI node with specified seed you can do. + + KNAPSACK_PRO_TEST_SUITE_TOKEN_RSPEC=token \ + KNAPSACK_PRO_REPOSITORY_ADAPTER=git \ + KNAPSACK_PRO_PROJECT_DIR=~/projects/rails-app \ + KNAPSACK_PRO_CI_NODE_TOTAL=2 \ + KNAPSACK_PRO_CI_NODE_INDEX=0 \ + bundle exec rake "knapsack_pro:rspec[--seed 123]" + +Above example is for RSpec. You can use respectively rake task name and token environment variable when you want to run tests for minitest, cucumber or spinach. ## Gem tests ### Spec