UG: Document JSON data format (#3902) and enhance related docs.

pekkaklarck · pekkaklarck · commit 2ca377fd6cd7 · 2023-06-11T19:17:54.000+03:00
Includes:
- Using JSON suite files.
- Using JSON resource files.
- Using reST resource files.
- Recommend `.resource` with normal resource files more strongly.
- List all supported extensions under Registrations.

Also document reST resource files.
diff --git a/doc/userguide/src/Appendices/Registrations.rst b/doc/userguide/src/Appendices/Registrations.rst
@@ -4,11 +4,44 @@ Registrations
 This appendix lists file extensions, media types, and so on, that are
 associated with Robot Framework.
 
-File extensions
----------------
+Suite file extensions
+---------------------
 
-- Robot Framework `suite files`_ use the :file:`.robot` extension.
-- Robot Framework `resource files`_ use the :file:`.resource` extension.
+`Suite files`_ with the following extensions are parsed automatically:
+
+:file:`.robot`
+    Suite file using the `plain text format`_.
+
+:file:`.robot.rst`
+    Suite file using the `reStructuredText format`_.
+
+:file:`.rbt`
+    Suite file using the `JSON format`_.
+
+Using other extensions is possible, but it requires `separate configuration`__.
+
+__ `Selecting files to parse`_
+
+Resource file extensions
+------------------------
+
+`Resource files`_ can use the following extensions:
+
+:file:`.resource`
+    Recommended when using the plain text format.
+
+:file:`.robot`, :file:`.txt` and :file:`.tsv`
+    Supported with the plain text format for backwards compatibility reasons.
+    :file:`.resource` is recommended and may be mandated in the future.
+
+:file:`.rst` and :file:`.rest`
+    Resource file using the `reStructuredText format`__.
+
+:file:`.rsrc` and :file:`.json`
+    Resource file using the `JSON format`__.
+
+__ `Resource files using reStructured text format`_
+__ `Resource files using JSON format`_
 
 Media type
 ----------
diff --git a/doc/userguide/src/CreatingTestData/ResourceAndVariableFiles.rst b/doc/userguide/src/CreatingTestData/ResourceAndVariableFiles.rst
@@ -5,7 +5,7 @@ User keywords and variables in `suite files`_ and `suite
 initialization files`_ can only be used in files where they are
 created, but *resource files* provide a mechanism for sharing them.
 The high level syntax for creating resource files is exactly the same
-as when creating test case files and `supported file formats`_ are the same
+as when creating suite files and `supported file formats`_ are the same
 as well. The main difference is that resource files cannot have tests.
 
 *Variable files* provide a powerful mechanism for creating and sharing
@@ -21,13 +21,20 @@ also makes them somewhat more complicated than `Variable sections`_.
 Resource files
 --------------
 
+Resource files are typically created using the plain text format, but also
+`reStructuredText format`__ and `JSON format`__ are supported.
+
+__ `Resource files using reStructured text format`_
+__ `Resource files using JSON format`_
+
 Taking resource files into use
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Resource files are imported using the :setting:`Resource` setting in the
 Settings section so that the path to the resource file is given as an argument
-to the setting. The recommended extension for resource files is
-:file:`.resource`, but also the normal :file:`.robot` extension works.
+to the setting. The recommended extension for resource files is :file:`.resource`.
+For backwards compatibility reasons also :file:`.robot`, :file:`.txt` and
+:file:`.tsv` work, but using :file:`.resource` may be mandated in the future.
 
 If the resource file path is absolute, it is used directly. Otherwise,
 the resource file is first searched relatively to the directory
@@ -47,7 +54,7 @@ are automatically changed to backslashes (:codesc:`\\`) on Windows.
 
    *** Settings ***
    Resource    example.resource
-   Resource    ../data/resources.robot
+   Resource    ../resources/login.resource
    Resource    package/example.resource
    Resource    ${RESOURCES}/common.resource
 
@@ -65,11 +72,12 @@ Resource file structure
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 The higher-level structure of resource files is the same as that of
-test case files otherwise, but, of course, they cannot contain Test
-Case sections. Additionally, the Setting section in resource files can
-contain only import settings (:setting:`Library`, :setting:`Resource`,
-:setting:`Variables`) and :setting:`Documentation`. The Variable section and
-Keyword section are used exactly the same way as in test case files.
+suite files otherwise, but they cannot contain tests or tasks.
+Additionally, the Setting section in resource files can contain only imports
+(:setting:`Library`, :setting:`Resource`, :setting:`Variables`),
+:setting:`Documentation` and :setting:`Keyword Tags`.
+The Variable section and Keyword section are used exactly the same way
+as in suite files.
 
 If several resource files have a user keyword with the same name, they
 must be used so that the `keyword name is prefixed with the resource
@@ -126,6 +134,87 @@ Example resource file
        [Arguments]    ${password}
        Input Text    password_field    ${password}
 
+Resource files using reStructured text format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `reStructuredText format`_ that can be used with `suite files`_  works
+also with resource files. Such resource files can use either :file:`.rst`
+or :file:`.rest` extension and they are otherwise imported exactly as
+normal resource files:
+
+.. sourcecode:: robotframework
+
+   *** Settings ***
+   Resource         example.rst
+
+When parsing resource files using the reStructuredText format, Robot Framework
+ignores all data outside code blocks containing Robot Framework data exactly
+the same way as when parsing `reStructuredText suite files`__.
+For example, the following resource file imports :name:`OperatingSystem` library,
+defines `${MESSAGE}` variable and creates :name:`My Keyword` keyword:
+
+.. sourcecode:: rest
+
+    Resource file using reStructuredText
+    ------------------------------------
+
+    This text is outside code blocks and thus ignored.
+
+    .. code:: robotframework
+
+       *** Settings ***
+       Library          OperatingSystem
+
+       *** Variables ***
+       ${MESSAGE}       Hello, world!
+
+    Also this text is outside code blocks and ignored. Code blocks not
+    containing Robot Framework data are ignored as well.
+
+    .. code:: robotframework
+
+       # Both space and pipe separated formats are supported.
+
+       | *** Keywords ***  |                        |         |
+       | My Keyword        | [Arguments]            | ${path} |
+       |                   | Directory Should Exist | ${path} |
+
+__ `reStructuredText format`_
+
+Resource files using JSON format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Resource files can be created using JSON_ the `same way as suite files`__.
+Such JSON resource files must use either the standard :file:`.json` extension
+or the custom :file:`.rsrc` extension. They are otherwise imported exactly as
+normal resource files:
+
+.. sourcecode:: robotframework
+
+   *** Settings ***
+   Resource         example.rsrc
+
+Resource files can be converted to JSON using `ResourceFile.to_json`__ and
+recreated using `ResourceFile.from_json`__:
+
+.. sourcecode:: python
+
+   from robot.running import ResourceFile
+
+
+   # Create resource file based on data on the file system.
+   resource = ResourceFile.from_file_system('example.resource')
+
+   # Save JSON data to a file.
+   resource.to_json('example.rsrc')
+
+   # Recreate resource from JSON data.
+   resource = ResourceFile.from_json('example.rsrc')
+
+__ `JSON format`_
+__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.running.html#robot.running.model.ResourceFile.to_json
+__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.running.html#robot.running.model.ResourceFile.from_json
+
 Variable files
 --------------
 
diff --git a/doc/userguide/src/CreatingTestData/TestDataSyntax.rst b/doc/userguide/src/CreatingTestData/TestDataSyntax.rst
@@ -106,17 +106,21 @@ and their arguments, are separated from each others with two or more spaces.
 An alternative is using the `pipe separated format`_ where the separator is
 the pipe character surrounded with spaces (:codesc:`\ |\ `).
 
-Executed files typically use the :file:`.robot` extension, but that `can be
-configured`__ with the :option:`--extension` option. `Resource files`_
-can use the :file:`.robot` extension as well, but using the dedicated
-:file:`.resource` extension is recommended. Files containing non-ASCII
+Suite files typically use the :file:`.robot` extension, but what files are
+parsed `can be configured`__. `Resource files`_ can use the :file:`.robot`
+extension as well, but using the dedicated :file:`.resource` extension is
+recommended and may be mandated in the future. Files containing non-ASCII
 characters must be saved using the UTF-8 encoding.
 
-Robot Framework also supports reStructuredText_ files so that normal
-Robot Framework data is `embedded into code blocks`__. It is possible to
-use either :file:`.rst` or :file:`.rest` extension with reStructuredText
-files, but the aforementioned :option:`--extension` option `must be used`__
-to enable parsing them when executing a directory.
+Robot Framework supports also reStructuredText_ files so that normal
+Robot Framework data is `embedded into code blocks`__. Only files with
+the :file:`.robot.rst` extension are parsed by default. If you would
+rather use just :file:`.rst` or :file:`.rest` extension, that needs to be
+configured separately.
+
+Robot Framework data can also be created in `JSON format`_ that is targeted
+more for tool developers than normal Robot Framework users. Only JSON files
+with the custom :file:`.rbt` extension are parsed by default.
 
 Earlier Robot Framework versions supported data also in HTML and TSV formats.
 The TSV format still works if the data is compatible with the `space separated
@@ -129,9 +133,9 @@ format at all.
 
 __ `Selecting files to parse`_
 __ `reStructuredText format`_
-__ `Selecting files to parse`_
 
 .. _space separated plain text format:
+.. _plain text format:
 
 Space separated format
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -314,7 +318,116 @@ when processing files using reStructuredText tooling normally.
 JSON format
 ~~~~~~~~~~~
 
-FIXME
+Robot Framework supports data also in JSON_ format. This format is designed
+more for tool developers than for regular Robot Framework users and it is not
+meant to be edited manually. Its most important use cases are:
+
+- Transferring data between processes and machines. A suite can be converted
+  to JSON in one machine and recreated somewhere else.
+- Saving a suite constructed from normal Robot Framework data into a single
+  JSON file that is faster to parse.
+- Alternative data format for external tools generating tests or tasks.
+
+.. note:: The JSON data support is new in Robot Framework 6.1 and it can be
+          enhanced in future Robot Framework versions. If you have an enhancement
+          idea or believe you have encountered a bug, please submit an issue__
+          or start a discussion thread on the `#devel` channel on our Slack_.
+
+__ https://issues.robotframework.org
+
+Converting suite to JSON
+''''''''''''''''''''''''
+
+A suite structure can be serialized into JSON by using the `TestSuite.to_json`__
+method. When used without arguments, it returns JSON data as a string, but
+it also accepts a path or an open file where to write JSON data along with
+configuration options related to JSON formatting:
+
+.. sourcecode:: python
+
+   from robot.running import TestSuite
+
+
+   # Create suite based on data on the file system.
+   suite = TestSuite.from_file_system('/path/to/data')
+   # Get JSON data as a string.
+   data = suite.to_json()
+   # Save JSON data to a file with custom indentation.
+   suite.to_json('data.rbt', indent=2)
+
+If you would rather work with Python data and then convert that to JSON
+or some other format yourself, you can use `TestSuite.to_dict`__ instead.
+
+__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.running.html#robot.running.model.TestSuite.to_json
+__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.running.html#robot.running.model.TestSuite.to_dict
+
+Creating suite from JSON
+''''''''''''''''''''''''
+
+A suite can be constructed from JSON data using the `TestSuite.from_json`__
+method. It works both with JSON strings and paths to JSON files:
+
+.. sourcecode:: python
+
+   from robot.running import TestSuite
+
+
+   # Create suite from JSON data in a file.
+   suite = TestSuite.from_json('data.rbt')
+   # Create suite from a JSON string.
+   suite = TestSuite.from_json('{"name": "Suite", "tests": [{"name": "Test"}]}')
+
+If you have data as a Python dictionary, you can use `TestSuite.from_dict`__
+instead.
+
+__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.running.html#robot.running.model.TestSuite.from_json
+__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.running.html#robot.running.model.TestSuite.from_dict
+
+Executing JSON files
+''''''''''''''''''''
+
+When using the `robot` command normally, JSON files with the :file:`.rbt`
+extension are parsed automatically. This includes running individual JSON files
+like `robot tests.rbt` and running directories containing :file:`.rbt` files.
+If you would rather use the standard :file:`.json` extension, you need to
+`configure which files are parsed`__.
+
+__ `Selecting files to parse`_
+
+Adjusting suite source
+''''''''''''''''''''''
+
+Suite source in the data got from `TestSuite.to_json` and `TestSuite.to_dict`
+is in absolute format. If a suite is recreated later on a different machine,
+the source may thus not match the directory structure on that machine. To
+avoid that, it is possible to use the `TestSuite.adjust_source`__ method to
+make the suite source relative before getting the data and add a correct root
+directory after the suite is recreated:
+
+.. sourcecode:: python
+
+   from robot.running import TestSuite
+
+
+   # Create a suite, adjust source and convert to JSON.
+   suite = TestSuite.from_file_system('/path/to/data')
+   suite.adjust_source(relative_to='/path/to')
+   suite.to_json('data.rbt')
+
+   # Recreate suite elsewhere and adjust source accordingly.
+   suite = TestSuite.from_json('data.rbt')
+   suite.adjust_source(root='/new/path/to')
+
+__ https://robot-framework.readthedocs.io/en/master/autodoc/robot.running.html#robot.running.model.TestSuite.adjust_source
+
+JSON structure
+''''''''''''''
+
+Imports, variables and keywords created in suite files are included in the
+generated JSON along with tests and tasks. The exact JSON structure is documented
+in the :file:`running.json` `schema file`__.
+
+__ https://github.com/robotframework/robotframework/tree/master/doc/schema#readme
 
 Rules for parsing the data
 --------------------------
