Document instance-settling #411, #441

_data/documentation.yml

@@ -117,10 +117,11 @@
   - config-dtd-processing
   - config-traces-debugging
 
-- title: Global variables
+- title: Variables
   docs:
   - variable-define
   - variable-override
+  - variable-instance
 
 - title: Metadata
   docs:

_documentation/metadata-concept.md

@@ -1,7 +1,7 @@
 ---
 layout: documentation
 title: Concept of metadata
-prev_section: variable-override
+prev_section: variable-instance
 next_section: metadata-description
 permalink: /docs/metadata-concept/
 ---

_documentation/variable-instance.md

@@ -0,0 +1,41 @@
+---
+layout: documentation
+title: Instance variables
+prev_section: variable-override
+next_section: metadata-concept
+permalink: /docs/variable-instance/
+---
+Version 1.20 introduces the notion of *instance variable*. This option offers the opportunity to define a single test and execute it several time with small details changing. These small details are handled by *variables*.
+
+## Instance-settling
+
+To define that a test must be executed several times, you must specify an xml element named *instance-settling*. This element is expecting a single variable (element *local-variable*) having a *name* and a *type*. The different values that this variable will take can be defined by the means of a [sequence](../primitive-sequence).
+
+{% highlight xml %}
+<instance-settling>
+  <local-variable name="firstDayOfMonth" type="dateTime">
+    <loop-sentinel seed="2016-01-01" terminal="2016-03-01" step="1 month"/>
+  </local-variable>
+</instance-settling>
+{% endhighlight %}
+
+## Customize categories, traits and name
+
+Based on the value of the local-variable, you can customize the name of the test but also the [*categories*](../metadata-category) and [*traits*](../metadata-trait).
+
+To achieve this add some xml elements in the *instance-settling* such as *category* and *trait*.
+
+{% highlight xml %}
+<test name="~Instance also defines the test's name and categories and traits for {@firstDayOfMonth:MMMM}" uid="0002">
+  <instance-settling>
+    <local-variable name="firstDayOfMonth" type="dateTime">
+      <loop-sentinel seed="2016-01-01" terminal="2016-03-01" step="1 month"/>
+    </local-variable>
+    <category>~{@firstDayOfMonth:MMMM}</category>
+    <trait name="Year">~{@firstDayOfMonth:yyyy}</trait>
+    <trait name="Month">~{@firstDayOfMonth:MM}</trait>
+    <trait name="Date">@firstDayOfMonth</trait>
+  </instance-settling>
+  ...
+</test>
+{% endhighlight %}