Skip to content

Commit

Permalink
Update docs for templating
Browse files Browse the repository at this point in the history
  • Loading branch information
@tommysitu
tommysitu committed Apr 20, 2024
1 parent ff5b46f commit 448d471
Showing 1 changed file with 104 additions and 77 deletions.
181 changes: 104 additions & 77 deletions docs/pages/keyconcepts/templating/templating.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -170,80 +170,10 @@ For example, you can generate a random name using the following expression:
Fakers that require arguments are currently not supported.

Maths Operation
CSV Data Source
~~~~~~~~~~~~~~~

The basic maths operations are currently supported: add, subtract, multiply and divide. These functions
take three parameters: two values it operates on and the precision. The precision is given in a string
format such as ``'0.00'``. For example ``{{ add 3 2.5 '0.00' }}`` should give you ``5.50``.
If no format is given, the exact value will be printed with up to 6 decimal places.

+------------+---------------------------------+---------------+
| Description| Example | Result |
+============+=================================+===============+
| Add | ``{{ add 10 3 '0.00' }}`` | 13.33 |
+------------+---------------------------------+---------------+
| Subtract | ``{{ subtract 10 3 '' }}`` | 7 |
+------------+---------------------------------+---------------+
| Multiply | ``{{ multiply 10 3 '' }}`` | 30 |
+------------+---------------------------------+---------------+
| Divide | ``{{ divide 10 3 '' }}`` | 3.333333 |
+------------+---------------------------------+---------------+

A math functions for summing an array of numbers is also supported, but it's usually used in conjunction
with the ``#each`` block helper. For example:

With the request payload of

.. code:: json
{
"lineitems": {
"lineitem": [
{
"upc": "1001",
"quantity": "1",
"price": "3.50"
},
{
"upc": "1002",
"quantity": "2",
"price": "4.50"
}
]
}
}
We can get the total price of all the line items using this templating function:


``{{#each (Request.Body 'jsonpath' '$.lineitems.lineitem') }}``
``{{ addToArray 'subtotal' (multiply (this.price) (this.quantity) '') false }} {{/each}}``
``total: {{ sum (getArray 'subtotal') '0.00' }}``

String Operation
~~~~~~~~~~~~~~~~

You can use the following helper methods to join, split or replace string values.

+-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
| Description | Example | Result |
+===========================================================+===========================================================+=========================================+
| String concatenate | ``{{ concat 'bee' 'hive' }}`` | beehive |
+-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
| String splitting | ``{{ split 'bee,hive' ',' }}`` | []string{"bee", "hive"} |
+-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
| Replace all occurrences of the old value with the new | ``{{ replace (Request.Body 'jsonpath' '$.text')`` | |
| | ``'be' 'mock' }}`` | |
| value in the target string | (where Request.Body has the value of | |
| | | |
| | ``{"text":"to be or not to be"}`` | to mock or not to mock |
+-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+

Templating Data Source
~~~~~~~~~~~~~~~~~~~~~~

User can upload CSV data file using hoverfly/hoverctl CLI or Admin API that can be queried via templating function.
You can query data from a CSV data source.

.. code:: json
Expand All @@ -253,11 +183,11 @@ User can upload CSV data file using hoverfly/hoverctl CLI or Admin API that can
.. note::

Data source name is case sensitive whereas other parameters in this function are case insensitive.
You can use hoverctl or call the Admin API to upload CSV data source to a running hoverfly instance.
The data source name is case sensitive whereas other parameters in this function are case insensitive.
You can use hoverctl or call the Admin API to upload CSV data source to a running Hoverfly instance.


Example: Start hoverfly with templating CSV datasource(student-marks.csv) provided below.
Example: Start Hoverfly with a CSV data source (student-marks.csv) provided below.

.. code:: bash
Expand Down Expand Up @@ -297,8 +227,8 @@ Example: Start hoverfly with templating CSV datasource(student-marks.csv) provid
+-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+


Journal
~~~~~~~
Journal Entry Data
~~~~~~~~~~~~~~~~~~

Journal Entry can be queried using its index and its extracted value.

Expand All @@ -325,6 +255,103 @@ Example:
In the above example, we are querying the name from JSON response in the journal entry where index ``Request.QueryParam.id`` has a key value of 1.

Key Value Data Store
~~~~~~~~~~~~~~~~~~~~

Sometimes you may need to store a temporary variable and retrieve it later in other part of the templated response.
In this case, you can use the internal key value data store. The following helper methods are available:

+----------------------------+--------------------------------------------+-----------------------+
| Description | Example | Result |
+============================+============================================+=======================+
| Put an entry | ``{{ putValue 'id' 123 true }}`` | 123 |
+----------------------------+--------------------------------------------+-----------------------+
| Get an entry | ``{{ getValue 'id' }}`` | 123 |
+----------------------------+--------------------------------------------+-----------------------+
| Add a value to an arra | ``{{ addToArray 'names' 'John' true }}`` | John |
+----------------------------+--------------------------------------------+-----------------------+
| Get an array | ``{{ getArray 'names' }}`` | []string{"John" |
+----------------------------+--------------------------------------------+-----------------------+

``addToArray`` will create a new array if one doesn't exist. The boolean argument in ``putValue`` and ``addToArray``
is used to control whether the set value is returned.

.. note::

Each templating session has its own key value store, which means all the data you set will be cleared after the current response is rendered.


Maths Operation
~~~~~~~~~~~~~~~

The basic maths operations are currently supported: add, subtract, multiply and divide. These functions
take three parameters: two values it operates on and the precision. The precision is given in a string
format such as ``'0.00'``. For example ``{{ add 3 2.5 '0.00' }}`` should give you ``5.50``.
If no format is given, the exact value will be printed with up to 6 decimal places.

+------------+---------------------------------+---------------+
| Description| Example | Result |
+============+=================================+===============+
| Add | ``{{ add 10 3 '0.00' }}`` | 13.33 |
+------------+---------------------------------+---------------+
| Subtract | ``{{ subtract 10 3 '' }}`` | 7 |
+------------+---------------------------------+---------------+
| Multiply | ``{{ multiply 10 3 '' }}`` | 30 |
+------------+---------------------------------+---------------+
| Divide | ``{{ divide 10 3 '' }}`` | 3.333333 |
+------------+---------------------------------+---------------+

A math functions for summing an array of numbers is also supported; it's usually used in conjunction
with the ``#each`` block helper. For example:

With the request payload of

.. code:: json
{
"lineitems": {
"lineitem": [
{
"upc": "1001",
"quantity": "1",
"price": "3.50"
},
{
"upc": "1002",
"quantity": "2",
"price": "4.50"
}
]
}
}
We can get the total price of all the line items using this templating function:


``{{#each (Request.Body 'jsonpath' '$.lineitems.lineitem') }}``
``{{ addToArray 'subtotal' (multiply (this.price) (this.quantity) '') false }} {{/each}}``
``total: {{ sum (getArray 'subtotal') '0.00' }}``

String Operation
~~~~~~~~~~~~~~~~

You can use the following helper methods to join, split or replace string values.

+-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
| Description | Example | Result |
+===========================================================+===========================================================+=========================================+
| String concatenate | ``{{ concat 'bee' 'hive' }}`` | beehive |
+-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
| String splitting | ``{{ split 'bee,hive' ',' }}`` | []string{"bee", "hive"} |
+-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+
| Replace all occurrences of the old value with the new | ``{{ replace (Request.Body 'jsonpath' '$.text')`` | |
| | ``'be' 'mock' }}`` | |
| value in the target string | (where Request.Body has the value of | |
| | | |
| | ``{"text":"to be or not to be"}`` | to mock or not to mock |
+-----------------------------------------------------------+-----------------------------------------------------------+-----------------------------------------+


Conditional Templating, Looping and More
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down

0 comments on commit 448d471

Please sign in to comment.