Clarify that only one data provider is combined with one other per combined label (#2118)

Author: Vampire

docs/data_driven_testing.adoc

@@ -342,6 +342,37 @@ NOTE: If a data table takes part in a cross-multiplication, accessing columns of
       data tables would not behave in an intuitive way and thus is currently forbidden. Accessing
       previous columns within one data table even works while taking part in a cross-multiplication.
 
+[NOTE]
+--
+Only the data provider right before the `combined:` label is
+combined with the data provider right after the `combined:` label.
+
+So if you execute
+[source,groovy,indent=0]
+----
+include::{sourcedir}/datadriven/DataSpec.groovy[tag=single-data-providers-combined1]
+----
+it will result in these executed tests:
+
+include::./{sourcedir}/datadriven/DataSpec.groovy[tag=single-data-providers-combined-result1,indent=0]
+
+If you want to combine `a` and `b` with `c` to get this result:
+
+include::./{sourcedir}/datadriven/DataSpec.groovy[tag=single-data-providers-combined-result2,indent=0]
+
+you have to for example use
+[source,groovy,indent=0]
+----
+include::{sourcedir}/datadriven/DataSpec.groovy[tag=single-data-providers-combined2]
+----
+or
+[source,groovy,indent=0]
+----
+include::{sourcedir}/datadriven/DataSpec.groovy[tag=single-data-providers-combined3]
+----
+--
+
+
 == Data Variable Assignment
 
 A data variable can be directly assigned a value:

spock-specs/src/test/groovy/org/spockframework/docs/datadriven/DataSpec.groovy

@@ -194,6 +194,123 @@ class DataSpec extends EmbeddedSpecification {
     }`""" == expected
   }
 
+  def "only single data providers are combined"() {
+    given:
+    def expected = '''
+      tag::single-data-providers-combined-result1[]
+      - `feature [a: 1, b: 5, c: 7, #0]`
+      - `feature [a: 2, b: 5, c: 8, #1]`
+      - `feature [a: 3, b: 6, c: 7, #2]`
+      - `feature [a: 4, b: 6, c: 8, #3]`
+      end::single-data-providers-combined-result1[]
+    '''
+      .stripIndent(*(GroovyRuntimeUtil.groovy3orNewer ? [true] : []))
+      .readLines()
+      .findAll {it.startsWith('-') }
+      .join('\n')
+      .trim()
+
+    when:
+    def result = runner.runSpecBody '''
+      def feature() {
+        expect:
+        true
+
+        // tag::single-data-providers-combined1[]
+        where:
+        a << [1, 2, 3, 4]
+        b << [5, 6]
+        combined:
+        c << [7, 8]
+        // end::single-data-providers-combined1[]
+      }
+    '''
+
+    then:
+    """- `${
+      result
+        .testEvents()
+        .succeeded()
+        .list()
+        *.testDescriptor
+        .findAll { it.type == TEST }
+        *.displayName
+        .join('`\n- `')
+    }`""" == expected
+
+    when:
+    expected = '''
+      tag::single-data-providers-combined-result2[]
+      - `feature [a: 1, b: 3, c: 5, #0]`
+      - `feature [a: 1, b: 3, c: 6, #1]`
+      - `feature [a: 2, b: 4, c: 5, #2]`
+      - `feature [a: 2, b: 4, c: 6, #3]`
+      end::single-data-providers-combined-result2[]
+    '''
+      .stripIndent(*(GroovyRuntimeUtil.groovy3orNewer ? [true] : []))
+      .readLines()
+      .findAll {it.startsWith('-') }
+      .join('\n')
+      .trim()
+    result = runner.runSpecBody '''
+      def feature() {
+        expect:
+        true
+
+        // tag::single-data-providers-combined2[]
+        where:
+        [a, b] << [
+          [1, 2],
+          [3, 4]
+        ].transpose()
+        combined:
+        c << [5, 6]
+        // end::single-data-providers-combined2[]
+      }
+    '''
+
+    then:
+    """- `${
+      result
+        .testEvents()
+        .succeeded()
+        .list()
+        *.testDescriptor
+        .findAll { it.type == TEST }
+        *.displayName
+        .join('`\n- `')
+    }`""" == expected
+
+    when:
+    result = runner.runSpecBody '''
+      def feature() {
+        expect:
+        true
+
+        // tag::single-data-providers-combined3[]
+        where:
+        a | b
+        1 | 3
+        2 | 4
+        combined:
+        c << [5, 6]
+        // end::single-data-providers-combined3[]
+      }
+    '''
+
+    then:
+    """- `${
+      result
+        .testEvents()
+        .succeeded()
+        .list()
+        *.testDescriptor
+        .findAll { it.type == TEST }
+        *.displayName
+        .join('`\n- `')
+    }`""" == expected
+  }
+
 // tag::sql-data-pipe[]
   def "maximum of two numbers"() {
     expect: