README.md in knapsack_pro-2.11.0 vs README.md in knapsack_pro-2.12.0

- old
+ new

@@ -70,23 +70,23 @@ - [Custom configuration](#custom-configuration) - [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 should you set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER=git` (required when CI provider is not supported)](#when-should-you-set-global-variable-knapsack_pro_repository_adaptergit-required-when-ci-provider-is-not-supported) + - [By default `KNAPSACK_PRO_REPOSITORY_ADAPTER` environment variable is undefined](#by-default-knapsack_pro_repository_adapter-environment-variable-is-undefined) + - [When should you set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER=git` (when CI provider is not supported and you use git)](#when-should-you-set-global-variable-knapsack_pro_repository_adaptergit-when-ci-provider-is-not-supported-and-you-use-git) + - [When you don't use git](#when-you-dont-use-git) - [Queue Mode](#queue-mode) - [How does queue mode work?](#how-does-queue-mode-work) - [How to use queue mode?](#how-to-use-queue-mode) - [Additional info about queue mode](#additional-info-about-queue-mode) - [Extra configuration for Queue Mode](#extra-configuration-for-queue-mode) - [KNAPSACK_PRO_FIXED_QUEUE_SPLIT (remember queue split on retry CI node)](#knapsack_pro_fixed_queue_split-remember-queue-split-on-retry-ci-node) - [KNAPSACK_PRO_MODIFY_DEFAULT_RSPEC_FORMATTERS (hide duplicated summary of pending and failed tests)](#knapsack_pro_modify_default_rspec_formatters-hide-duplicated-summary-of-pending-and-failed-tests) - [Supported test runners in queue mode](#supported-test-runners-in-queue-mode) - [Split test files by test cases](#split-test-files-by-test-cases) - [RSpec split test files by test examples (by individual `it`s)](#rspec-split-test-files-by-test-examples-by-individual-its) - - [Why I see error: Don't know how to build task 'knapsack_pro:rspec_test_example_detector'?](#why-i-see-error-dont-know-how-to-build-task-knapsack_prorspec_test_example_detector) - [How to manually define a list of slow test files to be split by test cases](#how-to-manually-define-a-list-of-slow-test-files-to-be-split-by-test-cases) - [Extra configuration for CI server](#extra-configuration-for-ci-server) - [Info about ENV variables](#info-about-env-variables) - [KNAPSACK_PRO_FIXED_TEST_SUITE_SPLIT (test suite split based on seed)](#knapsack_pro_fixed_test_suite_split-test-suite-split-based-on-seed) - [Environment variables for debugging gem](#environment-variables-for-debugging-gem) @@ -440,26 +440,34 @@ __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-should-you-set-global-variable-knapsack_pro_repository_adaptergit-required-when-ci-provider-is-not-supported). ### Repository adapter (How to set up 3 of 3) -#### When you NOT set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER` (default) +#### By default `KNAPSACK_PRO_REPOSITORY_ADAPTER` environment variable is undefined 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_BRANCH` - It's branch name. You run tests on this branch. `KNAPSACK_PRO_COMMIT_HASH` - Commit hash. You run tests for this commit. You can also use git as repository adapter to determine branch and commit hash, please see below section. -#### When should you set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER=git` (required when CI provider is not supported) +#### When should you set global variable `KNAPSACK_PRO_REPOSITORY_ADAPTER=git` (when CI provider is not supported and you use git) `KNAPSACK_PRO_REPOSITORY_ADAPTER` - When it has the value `git`, your local version of git on CI server will be used to get the branch name and commit hash. You also need to set `KNAPSACK_PRO_PROJECT_DIR` with the project directory path. `KNAPSACK_PRO_PROJECT_DIR` - Path to the project on the CI node, for instance `/home/ubuntu/my-app-repository`. It should be the top-level directory of your repository. +#### When you don't use git + +If your CI provider does not expose commit hash and branch name through environment variables, then `knapsack_pro` gem does not know these values. +You can manually set the values of the current commit hash and branch name in the environment variables: + +* `KNAPSACK_PRO_COMMIT_HASH` - commit hash. +* `KNAPSACK_PRO_BRANCH` - branch name. + ## Queue Mode knapsack_pro has a built-in queue mode designed to determine the optimal test suite split even when there is an unpredictably longer time execution of test files on one node (e.g. by CI node overload and decrease of performance that may affect how long the tests take on that node, or things like external requests done in individual tests). @@ -607,30 +615,22 @@ > __Note:__ This feature works for below test runners in Knapsack Pro Regular Mode and Queue Mode. ### RSpec split test files by test examples (by individual `it`s) +Read more about [this feature](https://knapsackpro.com/faq/question/how-to-split-slow-rspec-test-files-by-test-examples-by-individual-it) and [common problems here](https://knapsackpro.com/faq/question/how-to-split-slow-rspec-test-files-by-test-examples-by-individual-it#common-problems). + > ❗ __RSpec requirement:__ You need `RSpec >= 3.3.0` in order to use this feature. In order to split RSpec slow test files by test examples across parallel CI nodes you need to set environment variable: ``` KNAPSACK_PRO_RSPEC_SPLIT_BY_TEST_EXAMPLES=true ``` Thanks to that your CI build speed can be faster. We recommend using this feature with [Queue Mode](https://youtu.be/hUEB1XDKEFY) to ensure parallel CI nodes finish work at a similar time which gives you the shortest CI build time. -#### Why I see error: Don't know how to build task 'knapsack_pro:rspec_test_example_detector'? - -If you will see error like: - -``` -Don't know how to build task 'knapsack_pro:rspec_test_example_detector' (See the list of available tasks with `rake --tasks`) -``` - -It probably means bundler can't find the rake task. You can try to remove the default prefix `bundle exec` used by knapsack_pro gem by setting `KNAPSACK_PRO_RSPEC_TEST_EXAMPLE_DETECTOR_PREFIX=""`. - ### How to manually define a list of slow test files to be split by test cases If you don't want to rely on a list of test files from Knapsack Pro API to determine slow test files that should be split by test cases then you can define your own list of slow test files. ``` @@ -855,10 +855,11 @@ * develop * development * dev * master * staging +* [see full list of encryption excluded branch names](https://github.com/KnapsackPro/knapsack_pro-ruby/blob/master/lib/knapsack_pro/crypto/branch_encryptor.rb#L4) #### How to debug branch names? If you need to check what is the encryption hash for particular branch then use the rake task: @@ -1598,16 +1599,16 @@ options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5 strategy: fail-fast: false matrix: - # Set N number of parallel jobs you want to run tests on. - # Use higher number if you have slow tests to split them on more parallel jobs. - # Remember to update ci_node_index below to 0..N-1 + # [n] - where the n is a number of parallel jobs you want to run your tests on. + # Use a higher number if you have slow tests to split them between more parallel jobs. + # Remember to update the value of the `ci_node_index` below to (0..n-1). ci_node_total: [2] - # set N-1 indexes for parallel jobs - # When you run 2 parallel jobs then first job will have index 0, the second job will have index 1 etc + # Indexes for parallel jobs (starting from zero). + # E.g. use [0, 1] for 2 parallel jobs, [0, 1, 2] for 3 parallel jobs, etc. ci_node_index: [0, 1] steps: - uses: actions/checkout@v1 @@ -2062,23 +2063,10 @@ * you explicitly set `RAILS_ENV=test` on your CI nodes (for instance you use Docker then please set `RAILS_ENV`) * knapsack_pro Queue Mode saves temporary files with collected time execution data in `your_rails_project/tmp/knapsack_pro/queue/`. Please ensure you don't clean `tmp` directory in your tests so knapsack_pro can publish time execution data to Knapsack Pro API server. ##### Why all test files have 0.1s time execution for my CI build in user dashboard? -If you go to [user dashboard](https://knapsackpro.com/dashboard) and open `Build metrics` for your API token and you open CI build for your last git commit you should see there info about collected time execution data from all CI nodes. If you see all test files have 0.1s time execution then please ensure: - -* you should not clean up `tmp` directory in your tests (for instance in RSpec hooks like `before` or `after`) so knapsack_pro can publish measured time execution data to Knapsack Pro API server. knapsack_pro Queue Mode saves temporary files with collected time execution data in `your_rails_project/tmp/knapsack_pro/queue/`. -* please ensure you have in your `rails_helper.rb` or `spec_helper.rb` line that allows to measure tests: - -```ruby -require 'knapsack_pro' - -# CUSTOM_CONFIG_GOES_HERE - -KnapsackPro::Adapters::RSpecAdapter.bind -``` - -The 0.1s is a default time execution used when test file is an empty file or its content are all pending tests. +https://knapsackpro.com/faq/question/why-all-test-files-have-01s-time-execution-for-my-ci-build-in-user-dashboard ##### Why when I use Queue Mode for RSpec and test fails then I see multiple times info about failed test in RSpec result? The problem may happen when you use old knapsack_pro `< 0.33.0` or if you use custom rspec formatter, or when you set flag [KNAPSACK_PRO_MODIFY_DEFAULT_RSPEC_FORMATTERS=false](#knapsack_pro_modify_default_rspec_formatters-hide-duplicated-summary-of-pending-and-failed-tests).