Guide_Testing: add a note about get_test_file

emanuel-schmid · emanuel-schmid · commit a8c671633eff · 2023-12-13T15:28:46.000+01:00
diff --git a/doc/guide/Guide_Testing.ipynb b/doc/guide/Guide_Testing.ipynb
@@ -169,6 +169,37 @@
     "Anything written to `stdout` by a test method is useful mainly for the developer of the test."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Test files\n",
+    "\n",
+    "For integration tests it can be required to read data from a file, in order to set up a test that aims to check functionality with non-trivial data, beyond the scope of unit tests.\n",
+    "Some of thes test files can be found in the `climada/**/test/data` directories or in the `climada/data` directory. As mostly the case with large test data, it is not very well suitable for a Git repository.\n",
+    "\n",
+    "The preferable alternative is to post the data to the Climada Data-API with status `test_dataset` and retrieve the files on the fly from there during tests.\n",
+    "To do this one can use the convenience method `climada.test.get_test_file`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from climada.test import get_test_file\n",
+    "\n",
+    "my_test_file = get_test_file(ds_name='my-test-file', file_format='hdf5')  # returns a pathlib.Path object"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Behind the scenes, `get_test_file` uses the `climada.util.api_client.Client` to identify the appropriate dataset and downloads the respective file to the local dataset cache (`~/climada/data/*`)."
+   ]
+  },
   {
    "attachments": {},
    "cell_type": "markdown",
