diff --git a/docs/documentation/api.md b/docs/documentation/api.md index 233349efa1..9880ed874c 100644 --- a/docs/documentation/api.md +++ b/docs/documentation/api.md @@ -16,7 +16,7 @@ Our API documentation is defined by a few sets of files: docs](../documentation/user.html), with some special extensions for rendering nice code blocks and example responses. * The text for the Python examples comes from a test suite for the - Python API documentation (`zerver/lib/api_test_helpers.py`; run via + Python API documentation (`zerver/openapi/python_examples.py`; run via `tools/test-api`). The `generate_code_example` macro will magically read content from that test suite and render it as the code example. This structure ensures that Zulip's API documentation is robust to a @@ -93,7 +93,7 @@ Additionally, JavaScript examples should conform to the coding style and structure of [Zulip's existing JavaScript examples][javascript-examples]. For the Python examples, you'll write the example in -`zerver/lib/api_test_helpers.py`, and it'll be run and verified +`zerver/openapi/python_examples.py`, and it'll be run and verified automatically in Zulip's automated test suite. The code there will look something like this: @@ -201,7 +201,7 @@ above. [rest-api-tutorial]: ../tutorials/writing-views.html#writing-api-rest-endpoints 1. Add a function for the endpoint you'd like to document to - `zerver/lib/api_test_helpers.py`. `render_message` is a good + `zerver/openapi/python_examples.py`. `render_message` is a good example to follow. There are generally two key pieces to your test: (1) doing an API query and (2) verifying its result has the expected format using `validate_against_openapi_schema`. @@ -218,7 +218,7 @@ above. 1. Add the function to the `TEST_FUNCTIONS` dict and one of the `test_*` functions at the end of - `zerver/lib/api_test_helpers.py`; these will ensure your function + `zerver/openapi/python_examples.py`; these will ensure your function will be called when running `test-api`. 1. Capture the JSON response returned by the API call (the test diff --git a/docs/testing/testing.md b/docs/testing/testing.md index 039274c602..1d1d920f3d 100644 --- a/docs/testing/testing.md +++ b/docs/testing/testing.md @@ -68,7 +68,7 @@ Zulip also has about a dozen smaller tests suites: `/help` user documentation site, and related pages. - `tools/test-api`: Tests that the API documentation at `/api` actually works; the actual code for this is defined in - `zerver/lib/api_test_helpers.py`. + `zerver/openapi/python_examples.py`. - `test-locked-requirements`: Verifies that developers didn't forget to run `tools/update-locked-requirements` after modifying `requirements/*.in`. See diff --git a/tools/coveragerc b/tools/coveragerc index cb97c4ef4d..ae533f8f9e 100644 --- a/tools/coveragerc +++ b/tools/coveragerc @@ -26,7 +26,7 @@ omit = zerver/lib/test_fixtures.py zerver/lib/test_runner.py # Has its own independent test suite - zerver/lib/api_test_helpers.py + zerver/openapi/python_examples.py zerver/lib/parallel.py # Debugging tools that don't lend themselves well to unit tests zerver/lib/debug.py diff --git a/tools/linter_lib/custom_check.py b/tools/linter_lib/custom_check.py index 08660e08c8..1c2fba2b5b 100644 --- a/tools/linter_lib/custom_check.py +++ b/tools/linter_lib/custom_check.py @@ -47,7 +47,7 @@ FILES_WITH_LEGACY_SUBJECT = { 'zerver/tests/test_email_mirror.py', # These are tied more to our API than our DB model. - 'zerver/lib/api_test_helpers.py', + 'zerver/openapi/python_examples.py', 'zerver/tests/test_openapi.py', # This has lots of query data embedded, so it's hard @@ -449,7 +449,7 @@ python_rules = RuleList( 'puppet/', # Zerver files that we should just clean. 'zerver/tests', - 'zerver/lib/api_test_helpers.py', + 'zerver/openapi/python_examples.py', 'zerver/lib/request.py', 'zerver/views/streams.py', # thumbor is (currently) python2 only diff --git a/tools/test-api b/tools/test-api index 75194dfdb9..bfbf938af0 100755 --- a/tools/test-api +++ b/tools/test-api @@ -16,7 +16,7 @@ from zulip import Client from tools.lib.test_script import assert_provisioning_status_ok from tools.lib.test_server import test_server_running -from zerver.lib.api_test_helpers import test_the_api, test_invalid_api_key +from zerver.openapi.python_examples import test_the_api, test_invalid_api_key os.environ['DJANGO_SETTINGS_MODULE'] = 'zproject.test_settings' django.setup() diff --git a/tools/test-backend b/tools/test-backend index 6d1072c695..f95970906f 100755 --- a/tools/test-backend +++ b/tools/test-backend @@ -109,7 +109,7 @@ not_yet_fully_covered = {path for target in [ 'zerver/lib/generate_test_data.py', 'zerver/lib/test_fixtures.py', 'zerver/lib/test_runner.py', - 'zerver/lib/api_test_helpers.py', + 'zerver/openapi/python_examples.py', # Tornado should ideally have full coverage, but we're not there. 'zerver/tornado/autoreload.py', 'zerver/tornado/descriptors.py', diff --git a/zerver/lib/bugdown/api_code_examples.py b/zerver/lib/bugdown/api_code_examples.py index 1c49f0af27..67ddb21f41 100644 --- a/zerver/lib/bugdown/api_code_examples.py +++ b/zerver/lib/bugdown/api_code_examples.py @@ -7,7 +7,7 @@ from markdown.preprocessors import Preprocessor from typing import Any, Dict, Optional, List import markdown -import zerver.lib.api_test_helpers +import zerver.openapi.python_examples from zerver.lib.openapi import get_openapi_fixture MACRO_REGEXP = re.compile(r'\{generate_code_example(\(\s*(.+?)\s*\))*\|\s*(.+?)\s*\|\s*(.+?)\s*(\(\s*(.+)\s*\))?\}') @@ -55,7 +55,7 @@ def extract_python_code_example(source: List[str], snippet: List[str]) -> List[s return extract_python_code_example(source, snippet) def render_python_code_example(function: str, admin_config: Optional[bool]=False) -> List[str]: - method = zerver.lib.api_test_helpers.TEST_FUNCTIONS[function] + method = zerver.openapi.python_examples.TEST_FUNCTIONS[function] function_source_lines = inspect.getsourcelines(method)[0] if admin_config: @@ -144,7 +144,7 @@ class APICodeExamplesPreprocessor(Preprocessor): path, method = function.rsplit(':', 1) fixture_dict = get_openapi_fixture(path, method, name) else: - fixture_dict = zerver.lib.api_test_helpers.FIXTURES[function] + fixture_dict = zerver.openapi.python_examples.FIXTURES[function] fixture_json = json.dumps(fixture_dict, indent=4, sort_keys=True, separators=(',', ': ')) diff --git a/zerver/lib/api_test_helpers.py b/zerver/openapi/python_examples.py similarity index 100% rename from zerver/lib/api_test_helpers.py rename to zerver/openapi/python_examples.py