Skip to content

Commit

Permalink
Document --only-group grouping strategy choice (#870)
Browse files Browse the repository at this point in the history
The documentation says that parallel_test will attempt to use a runtime
grouping strategy if a runtime file is present and otherwise fall back
to the filesize strategy. This behavior can be overridden with an
explicit `--group-by` flag.

The `--only-group` flag changes this by always running with the filesize
strategy when no explicit strategy is given, even if a runtime file is
present. This behavior happens in `lib/parallel_tests/cli.rb:312`.

I was attempting to rely on the default behavior and also use the
`--only-group` flag and couldn't figure out why my runtime log wasn't
getting used. Only by reading the source did I figure out this
undocumented edge-case in the `--only-group` flag.

This commit adds explicit documentation about this. If you want to use
the `--only-group` flag and a runtime log, you _must_ explicitly set the
`--group-by` flag instead of relying on the default behavior.
  • Loading branch information
JoelQ authored Sep 6, 2023
1 parent 3247815 commit 432b80a
Show file tree
Hide file tree
Showing 3 changed files with 15 additions and 2 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@

### Added

- Document unexpected behavior where the `--only-group` flag will also set a
grouping strategy.

### Fixed

## 4.2.0 - 2023-02-06
Expand Down
4 changes: 3 additions & 1 deletion Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,9 @@ Options are:
Process 1 will contain 1_spec.rb and 2_spec.rb
Process 2 will contain 3_spec.rb
Process 3 will contain all other specs
--only-group INT[,INT]
--only-group INT[,INT] Only run the given group numbers. Note that this will force the 'filesize'
grouping strategy (even when the runtime log is present) unless you explicitly
set it otherwise via the '-group-by' flag.
-e, --exec [COMMAND] execute this code parallel and with ENV['TEST_ENV_NUMBER']
-o, --test-options '[OPTIONS]' execute test commands with those options
-t, --type [TYPE] test(default) / rspec / cucumber / spinach
Expand Down
10 changes: 9 additions & 1 deletion lib/parallel_tests/cli.rb
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,15 @@ def parse_options!(argv)
TEXT
) { |groups| options[:specify_groups] = groups }

opts.on("--only-group INT[,INT]", Array) { |groups| options[:only_group] = groups.map(&:to_i) }
opts.on(
"--only-group INT[,INT]",
Array,
<<~TEXT.rstrip.split("\n").join("\n#{newline_padding}")
Only run the given group numbers. Note that this will force the 'filesize'
grouping strategy (even when the runtime log is present) unless you explicitly
set it otherwise via the '-group-by' flag.
TEXT
) { |groups| options[:only_group] = groups.map(&:to_i) }

opts.on("-e", "--exec [COMMAND]", "execute this code parallel and with ENV['TEST_ENV_NUMBER']") { |arg| options[:execute] = Shellwords.shellsplit(arg) }
opts.on("-o", "--test-options '[OPTIONS]'", "execute test commands with those options") { |arg| options[:test_options] = Shellwords.shellsplit(arg) }
Expand Down

0 comments on commit 432b80a

Please sign in to comment.