From 448d4719b8e81978b470377401e2d85f206417f9 Mon Sep 17 00:00:00 2001 From: Tommy Situ Date: Sat, 20 Apr 2024 18:45:49 +0100 Subject: [PATCH] Update docs for templating --- .../keyconcepts/templating/templating.rst | 181 ++++++++++-------- 1 file changed, 104 insertions(+), 77 deletions(-) diff --git a/docs/pages/keyconcepts/templating/templating.rst b/docs/pages/keyconcepts/templating/templating.rst index c1131d91b..edd0ce2f2 100644 --- a/docs/pages/keyconcepts/templating/templating.rst +++ b/docs/pages/keyconcepts/templating/templating.rst @@ -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 @@ -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 @@ -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. @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~