• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

ruby-grape / grape / 17881304237

20 Sep 2025 02:55PM UTC coverage: 96.666% (-1.5%) from 98.194%
17881304237

Pull #2604

github

ericproulx
Enable branch coverage in SimpleCov configuration

- Add enable_coverage :branch to SimpleCov.start block
- Improves test coverage reporting by tracking branch coverage
- Helps identify untested code paths and conditional logic
Pull Request #2604: Enable Branch Coverage in SimpleCov Configuration

1072 of 1163 branches covered (92.18%)

Branch coverage included in aggregate %.

23 of 23 new or added lines in 7 files covered. (100.0%)

1 existing line in 1 file now uncovered.

3364 of 3426 relevant lines covered (98.19%)

49186.97 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

98.36
/lib/grape/validations/params_scope.rb
1
# frozen_string_literal: true
2

3
module Grape
44✔
4
  module Validations
44✔
5
    class ParamsScope
44✔
6
      attr_accessor :element, :parent, :index
44✔
7
      attr_reader :type, :params_meeting_dependency
44✔
8

9
      include Grape::DSL::Parameters
44✔
10
      include Grape::Validations::ParamsDocumentation
44✔
11

12
      # There are a number of documentation options on entities that don't have
13
      # corresponding validators. Since there is nowhere that enumerates them all,
14
      # we maintain a list of them here and skip looking up validators for them.
15
      RESERVED_DOCUMENTATION_KEYWORDS = %i[as required param_type is_array format example].freeze
44✔
16

17
      class Attr
44✔
18
        attr_accessor :key, :scope
44✔
19

20
        # Open up a new ParamsScope::Attr
21
        # @param key [Hash, Symbol] key of attr
22
        # @param scope [Grape::Validations::ParamsScope] scope of attr
23
        def initialize(key, scope)
44✔
24
          @key = key
136,500✔
25
          @scope = scope
136,500✔
26
        end
27

28
        # @return Array[Symbol, Hash[Symbol => Array]] declared_params with symbol instead of Attr
29
        def self.attrs_keys(declared_params)
44✔
30
          declared_params.map do |declared_param_attr|
740✔
31
            attr_key(declared_param_attr)
1,147✔
32
          end
33
        end
34

35
        def self.attr_key(declared_param_attr)
44✔
36
          return attr_key(declared_param_attr.key) if declared_param_attr.is_a?(self)
2,294✔
37

38
          if declared_param_attr.is_a?(Hash)
1,147✔
39
            declared_param_attr.transform_values { |value| attrs_keys(value) }
518✔
40
          else
41
            declared_param_attr
888✔
42
          end
43
        end
44
      end
45

46
      # Open up a new ParamsScope, allowing parameter definitions per
47
      #   Grape::DSL::Params.
48
      # @param opts [Hash] options for this scope
49
      # @option opts :element [Symbol] the element that contains this scope; for
50
      #   this to be relevant, @parent must be set
51
      # @option opts :element_renamed [Symbol, nil] whenever this scope should
52
      #   be renamed and to what, given +nil+ no renaming is done
53
      # @option opts :parent [ParamsScope] the scope containing this scope
54
      # @option opts :api [API] the API endpoint to modify
55
      # @option opts :optional [Boolean] whether or not this scope needs to have
56
      #   any parameters set or not
57
      # @option opts :type [Class] a type meant to govern this scope (deprecated)
58
      # @option opts :type [Hash] group options for this scope
59
      # @option opts :dependent_on [Symbol] if present, this scope should only
60
      #   validate if this param is present in the parent scope
61
      # @yield the instance context, open for parameter definitions
62
      def initialize(opts, &block)
44✔
63
        @element          = opts[:element]
105,394✔
64
        @element_renamed  = opts[:element_renamed]
105,394✔
65
        @parent           = opts[:parent]
105,394✔
66
        @api              = opts[:api]
105,394✔
67
        @optional         = opts[:optional] || false
105,394✔
68
        @type             = opts[:type]
105,394✔
69
        @group            = opts[:group]
105,394✔
70
        @dependent_on     = opts[:dependent_on]
105,394✔
71
        @params_meeting_dependency = []
105,394✔
72
        @declared_params = []
105,394✔
73
        @index = nil
105,394✔
74

75
        instance_eval(&block) if block
105,394✔
76

77
        configure_declared_params
104,469✔
78
      end
79

80
      def configuration
44✔
81
        @api.configuration.respond_to?(:evaluate) ? @api.configuration.evaluate : @api.configuration
555✔
82
      end
83

84
      # @return [Boolean] whether or not this entire scope needs to be
85
      #   validated
86
      def should_validate?(parameters)
44✔
87
        scoped_params = params(parameters)
183,447✔
88

89
        return false if @optional && (scoped_params.blank? || all_element_blank?(scoped_params))
183,447✔
90
        return false unless meets_dependency?(scoped_params, parameters)
176,150✔
91
        return true if parent.nil?
160,832✔
92

93
        parent.should_validate?(parameters)
54,205✔
94
      end
95

96
      def meets_dependency?(params, request_params)
44✔
97
        return true unless @dependent_on
334,318✔
98
        return false if @parent.present? && !@parent.meets_dependency?(@parent.params(request_params), request_params)
40,589✔
99

100
        if params.is_a?(Array)
40,515✔
101
          @params_meeting_dependency = params.flatten.filter { |param| meets_dependency?(param, request_params) }
7,511✔
102
          return @params_meeting_dependency.present?
2,368✔
103
        end
104

105
        meets_hash_dependency?(params)
38,147✔
106
      end
107

108
      def attr_meets_dependency?(params)
44✔
109
        return true unless @dependent_on
4,588✔
110
        return false if @parent.present? && !@parent.attr_meets_dependency?(params)
1,739✔
111

112
        meets_hash_dependency?(params)
1,628✔
113
      end
114

115
      def meets_hash_dependency?(params)
44✔
116
        # params might be anything what looks like a hash, so it must implement a `key?` method
117
        return false unless params.respond_to?(:key?)
39,775✔
118

119
        @dependent_on.each do |dependency|
39,738✔
120
          if dependency.is_a?(Hash)
39,923✔
121
            dependency_key = dependency.keys[0]
34,928✔
122
            proc = dependency.values[0]
34,928✔
123
            return false unless proc.call(params.try(:[], dependency_key))
34,928✔
124
          elsif params.respond_to?(:key?) && params.try(:[], dependency).blank?
4,995✔
125
            return false
1,554✔
126
          end
127
        end
128

129
        true
21,793✔
130
      end
131

132
      # @return [String] the proper attribute name, with nesting considered.
133
      def full_name(name, index: nil)
44✔
134
        if nested?
271,755✔
135
          # Find our containing element's name, and append ours.
136
          "#{@parent.full_name(@element)}#{brackets(index || @index)}#{brackets(name)}"
71,873✔
137
        elsif lateral?
199,882✔
138
          # Find the name of the element as if it was at the same nesting level
139
          # as our parent. We need to forward our index upward to achieve this.
140
          @parent.full_name(name, index: @index)
21,349✔
141
        else
142
          # We must be the root scope, so no prefix needed.
143
          name.to_s
178,533✔
144
        end
145
      end
146

147
      def brackets(val)
44✔
148
        "[#{val}]" if val
143,746✔
149
      end
150

151
      # @return [Boolean] whether or not this scope is the root-level scope
152
      def root?
44✔
153
        !@parent
111✔
154
      end
155

156
      # A nested scope is contained in one of its parent's elements.
157
      # @return [Boolean] whether or not this scope is nested
158
      def nested?
44✔
159
        @parent && @element
384,512✔
160
      end
161

162
      # A lateral scope is subordinate to its parent, but its keys are at the
163
      # same level as its parent and thus is not contained within an element.
164
      # @return [Boolean] whether or not this scope is lateral
165
      def lateral?
44✔
166
        @parent && !@element
360,728✔
167
      end
168

169
      # @return [Boolean] whether or not this scope needs to be present, or can
170
      #   be blank
171
      def required?
44✔
172
        !@optional
107,144✔
173
      end
174

175
      def reset_index
44✔
176
        @index = nil
114,360✔
177
      end
178

179
      protected
44✔
180

181
      # Adds a parameter declaration to our list of validations.
182
      # @param attrs [Array] (see Grape::DSL::Parameters#requires)
183
      def push_declared_params(attrs, opts = {})
44✔
184
        opts[:declared_params_scope] = self unless opts.key?(:declared_params_scope)
147,526✔
185
        return @parent.push_declared_params(attrs, opts) if lateral?
147,526✔
186

187
        push_renamed_param(full_path + [attrs.first], opts[:as]) if opts[:as]
133,873✔
188
        @declared_params.concat(attrs.map { |attr| ::Grape::Validations::ParamsScope::Attr.new(attr, opts[:declared_params_scope]) })
270,373✔
189
      end
190

191
      # Get the full path of the parameter scope in the hierarchy.
192
      #
193
      # @return [Array<Symbol>] the nesting/path of the current parameter scope
194
      def full_path
44✔
195
        if nested?
8,288✔
196
          (@parent.full_path + [@element])
5,328✔
197
        elsif lateral?
2,960✔
198
          @parent.full_path
37✔
199
        else
200
          []
2,923✔
201
        end
202
      end
203

204
      private
44✔
205

206
      # Add a new parameter which should be renamed when using the +#declared+
207
      # method.
208
      #
209
      # @param path [Array<String, Symbol>] the full path of the parameter
210
      #   (including the parameter name as last array element)
211
      # @param new_name [String, Symbol] the new name of the parameter (the
212
      #   renamed name, with the +as: ...+ semantic)
213
      def push_renamed_param(path, new_name)
44✔
214
        api_route_setting = @api.inheritable_setting.route
2,923✔
215
        base = api_route_setting[:renamed_params] || {}
2,923✔
216
        base[Array(path).map(&:to_s)] = new_name.to_s
2,923✔
217
        api_route_setting[:renamed_params] = base
2,923✔
218
      end
219

220
      def require_required_and_optional_fields(context, opts)
44✔
221
        if context == :all
444✔
222
          optional_fields = Array.wrap(opts[:except])
259✔
223
          required_fields = opts[:using].keys.delete_if { |f| optional_fields.include?(f) }
851✔
224
        else # context == :none
225
          required_fields = Array.wrap(opts[:except])
185✔
226
          optional_fields = opts[:using].keys.delete_if { |f| required_fields.include?(f) }
555✔
227
        end
228
        required_fields.each do |field|
444✔
229
          field_opts = opts[:using][field]
481✔
230
          raise ArgumentError, "required field not exist: #{field}" unless field_opts
481✔
231

232
          requires(field, field_opts)
444✔
233
        end
234
        optional_fields.each do |field|
407✔
235
          field_opts = opts[:using][field]
481✔
236
          optional(field, field_opts) if field_opts
481✔
237
        end
238
      end
239

240
      def require_optional_fields(context, opts)
44✔
241
        optional_fields = opts[:using].keys
259✔
242
        unless context == :all
259!
243
          except_fields = Array.wrap(opts[:except])
×
UNCOV
244
          optional_fields.delete_if { |f| except_fields.include?(f) }
×
245
        end
246
        optional_fields.each do |field|
259✔
247
          field_opts = opts[:using][field]
444✔
248
          optional(field, field_opts) if field_opts
444!
249
        end
250
      end
251

252
      def validate_attributes(attrs, opts, &block)
44✔
253
        validations = opts.clone
134,576✔
254
        validations[:type] ||= Array if block
134,576✔
255
        validates(attrs, validations)
134,576✔
256
      end
257

258
      # Returns a new parameter scope, subordinate to the current one and nested
259
      # under the parameter corresponding to `attrs.first`.
260
      # @param attrs [Array] the attributes passed to the `requires` or
261
      #   `optional` invocation that opened this scope.
262
      # @param optional [Boolean] whether the parameter this are nested under
263
      #   is optional or not (and hence, whether this block's params will be).
264
      # @yield parameter scope
265
      def new_scope(attrs, optional = false, &block)
44✔
266
        # if required params are grouped and no type or unsupported type is provided, raise an error
267
        type = attrs[1] ? attrs[1][:type] : nil
19,208✔
268
        if attrs.first && !optional
19,208✔
269
          raise Grape::Exceptions::MissingGroupType if type.nil?
6,253✔
270
          raise Grape::Exceptions::UnsupportedGroupType unless Grape::Validations::Types.group?(type)
6,216✔
271
        end
272

273
        self.class.new(
19,134✔
274
          api: @api,
275
          element: attrs.first,
276
          element_renamed: attrs[1][:as],
277
          parent: self,
278
          optional: optional,
279
          type: type || Array,
280
          group: @group,
281
          &block
282
        )
283
      end
284

285
      # Returns a new parameter scope, not nested under any current-level param
286
      # but instead at the same level as the current scope.
287
      # @param options [Hash] options to control how this new scope behaves
288
      # @option options :dependent_on [Symbol] if given, specifies that this
289
      #   scope should only validate if this parameter from the above scope is
290
      #   present
291
      # @yield parameter scope
292
      def new_lateral_scope(options, &block)
44✔
293
        self.class.new(
9,250✔
294
          api: @api,
295
          element: nil,
296
          parent: self,
297
          options: @optional,
298
          type: type == Array ? Array : Hash,
9,250✔
299
          dependent_on: options[:dependent_on],
300
          &block
301
        )
302
      end
303

304
      # Returns a new parameter scope, subordinate to the current one and nested
305
      # under the parameter corresponding to `attrs.first`.
306
      # @param attrs [Array] the attributes passed to the `requires` or
307
      #   `optional` invocation that opened this scope.
308
      # @yield parameter scope
309
      def new_group_scope(attrs, &block)
44✔
310
        self.class.new(api: @api, parent: self, group: attrs.first, &block)
2,664✔
311
      end
312

313
      # Pushes declared params to parent or settings
314
      def configure_declared_params
44✔
315
        push_renamed_param(full_path, @element_renamed) if @element_renamed
104,469✔
316

317
        if nested?
104,469✔
318
          @parent.push_declared_params [element => @declared_params]
19,134✔
319
        else
320
          @api.namespace_stackable(:declared_params, @declared_params)
85,335✔
321
        end
322

323
        # params were stored in settings, it can be cleaned from the params scope
324
        @declared_params = nil
104,469✔
325
      end
326

327
      def validates(attrs, validations)
44✔
328
        coerce_type = infer_coercion(validations)
137,869✔
329
        required = validations.key?(:presence)
137,832✔
330
        default = validations[:default]
137,832✔
331
        values = validations[:values].is_a?(Hash) ? validations.dig(:values, :value) : validations[:values]
137,832✔
332
        except_values = validations[:except_values].is_a?(Hash) ? validations.dig(:except_values, :value) : validations[:except_values]
137,832✔
333

334
        # NB. values and excepts should be nil, Proc, Array, or Range.
335
        # Specifically, values should NOT be a Hash
336
        # use values or excepts to guess coerce type when stated type is Array
337
        coerce_type = guess_coerce_type(coerce_type, values, except_values)
137,832✔
338

339
        # default value should be present in values array, if both exist and are not procs
340
        check_incompatible_option_values(default, values, except_values)
137,832✔
341

342
        # type should be compatible with values array, if both exist
343
        validate_value_coercion(coerce_type, values, except_values)
137,684✔
344

345
        document_params attrs, validations, coerce_type, values, except_values
137,351✔
346

347
        opts = derive_validator_options(validations)
137,351✔
348

349
        # Validate for presence before any other validators
350
        validates_presence(validations, attrs, opts)
137,351✔
351

352
        # Before we run the rest of the validators, let's handle
353
        # whatever coercion so that we are working with correctly
354
        # type casted values
355
        coerce_type validations, attrs, required, opts
137,351✔
356

357
        validations.each do |type, options|
137,240✔
358
          # Don't try to look up validators for documentation params that don't have one.
359
          next if RESERVED_DOCUMENTATION_KEYWORDS.include?(type)
81,882✔
360

361
          validate(type, options, attrs, required, opts)
78,219✔
362
        end
363
      end
364

365
      # Validate and comprehend the +:type+, +:types+, and +:coerce_with+
366
      # options that have been supplied to the parameter declaration.
367
      # The +:type+ and +:types+ options will be removed from the
368
      # validations list, replaced appropriately with +:coerce+ and
369
      # +:coerce_with+ options that will later be passed to
370
      # {Validators::CoerceValidator}. The type that is returned may be
371
      # used for documentation and further validation of parameter
372
      # options.
373
      #
374
      # @param validations [Hash] list of validations supplied to the
375
      #   parameter declaration
376
      # @return [class-like] type to which the parameter will be coerced
377
      # @raise [ArgumentError] if the given type options are invalid
378
      def infer_coercion(validations)
44✔
379
        raise ArgumentError, ':type may not be supplied with :types' if validations.key?(:type) && validations.key?(:types)
137,869✔
380

381
        validations[:coerce] = (options_key?(:type, :value, validations) ? validations[:type][:value] : validations[:type]) if validations.key?(:type)
137,832✔
382
        validations[:coerce_message] = (options_key?(:type, :message, validations) ? validations[:type][:message] : nil) if validations.key?(:type)
137,832✔
383
        validations[:coerce] = (options_key?(:types, :value, validations) ? validations[:types][:value] : validations[:types]) if validations.key?(:types)
137,832✔
384
        validations[:coerce_message] = (options_key?(:types, :message, validations) ? validations[:types][:message] : nil) if validations.key?(:types)
137,832✔
385

386
        validations.delete(:types) if validations.key?(:types)
137,832✔
387

388
        coerce_type = validations[:coerce]
137,832✔
389

390
        # Special case - when the argument is a single type that is a
391
        # variant-type collection.
392
        if Types.multiple?(coerce_type) && validations.key?(:type)
137,832✔
393
          validations[:coerce] = Types::VariantCollectionCoercer.new(
410✔
394
            coerce_type,
395
            validations.delete(:coerce_with)
396
          )
397
        end
398
        validations.delete(:type)
137,832✔
399

400
        coerce_type
137,832✔
401
      end
402

403
      # Enforce correct usage of :coerce_with parameter.
404
      # We do not allow coercion without a type, nor with
405
      # +JSON+ as a type since this defines its own coercion
406
      # method.
407
      def check_coerce_with(validations)
44✔
408
        return unless validations.key?(:coerce_with)
137,351✔
409
        # type must be supplied for coerce_with..
410
        raise ArgumentError, 'must supply type for coerce_with' unless validations.key?(:coerce)
1,073✔
411

412
        # but not special JSON types, which
413
        # already imply coercion method
414
        return if [JSON, Array[JSON]].exclude? validations[:coerce]
1,036✔
415

416
        raise ArgumentError, 'coerce_with disallowed for type: JSON'
74✔
417
      end
418

419
      # Add type coercion validation to this scope,
420
      # if any has been specified.
421
      # This validation has special handling since it is
422
      # composited from more than one +requires+/+optional+
423
      # parameter, and needs to be run before most other
424
      # validations.
425
      def coerce_type(validations, attrs, required, opts)
44✔
426
        check_coerce_with(validations)
137,351✔
427

428
        return unless validations.key?(:coerce)
137,240✔
429

430
        coerce_options = {
431
          type: validations[:coerce],
67,375✔
432
          method: validations[:coerce_with],
433
          message: validations[:coerce_message]
434
        }
435
        validate('coerce', coerce_options, attrs, required, opts)
67,375✔
436
        validations.delete(:coerce_with)
67,375✔
437
        validations.delete(:coerce)
67,375✔
438
        validations.delete(:coerce_message)
67,375✔
439
      end
440

441
      def guess_coerce_type(coerce_type, *values_list)
44✔
442
        return coerce_type unless coerce_type == Array
137,832✔
443

444
        values_list.each do |values|
12,843✔
445
          next if !values || values.is_a?(Proc)
25,612✔
446
          return values.first.class if values.is_a?(Range) || !values.empty?
74!
447
        end
448
        coerce_type
12,769✔
449
      end
450

451
      def check_incompatible_option_values(default, values, except_values)
44✔
452
        return unless default && !default.is_a?(Proc)
137,832✔
453

454
        raise Grape::Exceptions::IncompatibleOptionValues.new(:default, default, :values, values) if values && !values.is_a?(Proc) && !Array(default).all? { |def_val| values.include?(def_val) }
21,683✔
455

456
        return unless except_values && !except_values.is_a?(Proc) && Array(default).any? { |def_val| except_values.include?(def_val) }
15,023✔
457

458
        raise Grape::Exceptions::IncompatibleOptionValues.new(:default, default, :except, except_values)
74✔
459
      end
460

461
      def validate(type, options, attrs, required, opts)
44✔
462
        validator_options = {
463
          attributes: attrs,
206,355✔
464
          options: options,
465
          required: required,
466
          params_scope: self,
467
          opts: opts,
468
          validator_class: Validations.require_validator(type)
469
        }
470
        @api.namespace_stackable(:validations, validator_options)
206,355✔
471
      end
472

473
      def validate_value_coercion(coerce_type, *values_list)
44✔
474
        return unless coerce_type
137,684✔
475

476
        coerce_type = coerce_type.first if coerce_type.is_a?(Enumerable)
67,745✔
477
        values_list.each do |values|
67,745✔
478
          next if !values || values.is_a?(Proc)
135,231✔
479

480
          value_types = values.is_a?(Range) ? [values.begin, values.end].compact : values
16,798✔
481
          value_types = value_types.map { |type| Grape::API::Boolean.build(type) } if coerce_type == Grape::API::Boolean
18,389✔
482
          raise Grape::Exceptions::IncompatibleOptionValues.new(:type, coerce_type, :values, values) unless value_types.all?(coerce_type)
16,798✔
483
        end
484
      end
485

486
      def extract_message_option(attrs)
44✔
487
        return nil unless attrs.is_a?(Array)
3,293!
488

489
        opts = attrs.last.is_a?(Hash) ? attrs.pop : {}
3,293✔
490
        opts.key?(:message) && !opts[:message].nil? ? opts.delete(:message) : nil
3,293✔
491
      end
492

493
      def options_key?(type, key, validations)
44✔
494
        validations[type].respond_to?(:key?) && validations[type].key?(key) && !validations[type][key].nil?
134,824✔
495
      end
496

497
      def all_element_blank?(scoped_params)
44✔
498
        scoped_params.respond_to?(:all?) && scoped_params.all?(&:blank?)
12,432✔
499
      end
500

501
      # Validators don't have access to each other and they don't need, however,
502
      # some validators might influence others, so their options should be shared
503
      def derive_validator_options(validations)
44✔
504
        allow_blank = validations[:allow_blank]
137,351✔
505

506
        {
507
          allow_blank: allow_blank.is_a?(Hash) ? allow_blank[:value] : allow_blank,
274,702✔
508
          fail_fast: validations.delete(:fail_fast) || false
509
        }
510
      end
511

512
      def validates_presence(validations, attrs, opts)
44✔
513
        return unless validations.key?(:presence) && validations[:presence]
137,351✔
514

515
        validate('presence', validations.delete(:presence), attrs, true, opts)
60,761✔
516
        validations.delete(:message) if validations.key?(:message)
60,761✔
517
      end
518
    end
519
  end
520
end
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc