grosser/parallel_tests · error · RuntimeError

--group-by #{allowed.join(" or ")} is required for --only-gr

Error message

--group-by #{allowed.join(" or ")} is required for --only-group

What it means

--only-group re-runs a subset of previously computed groups, which only stays correct for deterministic grouping strategies. The CLI restricts the combination to filesize, runtime and found; note that when --only-group is given without --group-by, filesize is assumed (cli.rb:369), so this raise fires only when an explicitly incompatible value such as steps, scenarios or default is passed.

Source

Thrown at lib/parallel_tests/cli.rb:376

          if File.directory?(default_test_folder)
            files = [default_test_folder]
          else
            abort "Pass files or folders to run"
          end
        end
        options[:files] = files.map { |file_path| Pathname.new(file_path).cleanpath.to_s }
      end

      append_test_options(options, remaining)

      options[:group_by] ||= :filesize if options[:only_group]

      if options[:group_by] == :found && options[:single_process]
        raise "--group-by found and --single-process are not supported"
      end
      allowed = [:filesize, :runtime, :found]
      if !allowed.include?(options[:group_by]) && options[:only_group]
        raise "--group-by #{allowed.join(" or ")} is required for --only-group"
      end

      if options[:specify_groups] && options.keys.intersect?([:single_process, :isolate, :isolate_count])
        raise "Can't pass --specify-groups with any of these keys: --single, --isolate, or --isolate-n"
      end

      if options[:failure_exit_code] && options[:highest_exit_status]
        raise "Can't pass --failure-exit-code and --highest-exit-status"
      end

      options
    end

    def extract_file_paths(argv)
      dash_index = argv.rindex("--")
      file_args_at = (dash_index || -1) + 1
      [argv[file_args_at..], argv[0...(dash_index || 0)]]
    end

View on GitHub (pinned to a06047856d)

Solutions

  1. Remove the explicit --group-by -- with --only-group it defaults to filesize, which is deterministic and allowed
  2. Or set --group-by to runtime (with a populated runtime log) or found
  3. If steps/scenarios grouping is required, drop --only-group and select the files directly instead of group indexes

Example fix

# before
parallel_test -t cucumber --group-by steps --only-group 1

# after
parallel_test -t cucumber --only-group 1 # defaults to --group-by filesize
Defensive patterns

Strategy: validation

Validate before calling

ALLOWED_GROUP_BY = %w[filesize runtime found].freeze
opts = ENV.fetch('PARALLEL_TEST_OPTS', '').shellsplit
if (i = opts.index('--group-by')) && opts[i + 1] && !ALLOWED_GROUP_BY.include?(opts[i + 1]) && opts.include?('--only-group')
  abort "parallel_tests: --only-group needs --group-by #{ALLOWED_GROUP_BY.join(' or ')}"
end

Type guard

def only_group_compatible?(group_by)
  %w[filesize runtime found].include?(group_by)
end

Try / catch

begin
  ParallelTests::CLI.new.run(args)
rescue RuntimeError => e
  abort "#{e.message} -- omit --group-by (defaults to filesize) or use filesize/runtime/found"
end

Prevention

When it happens

Trigger: `parallel_test --group-by steps --only-group 1`; `--group-by scenarios --only-group 2,3`; any explicit --group-by value outside [:filesize, :runtime, :found] combined with --only-group, via CLI flags or a rake PARALLEL_TEST_OPTS string.

Common situations: Cucumber suites that use step-count grouping add --only-group to re-run a failed group on CI; job templates copy a --group-by from one CI job into another that already carried --only-group; debugging sessions temporarily set group_by to 'default' and leave it behind.

Related errors

AI-assisted analysis of grosser/parallel_tests@a06047856d (2026-08-23). Data as JSON: /api/errors/752c9a72c148c4b9. Report an issue: GitHub.