From 72160a319ec9cf94c4235ad4b11e0ab2ad395e6b Mon Sep 17 00:00:00 2001 From: Divyam Talwar Date: Tue, 30 Jun 2026 02:20:18 +0530 Subject: [PATCH] Document SDK live-test commands accurately SDK live tests read MORPHIK_TEST_URI, but the SDK docs told contributors to set MORPHIK_TEST_URL. Align the examples and environment-variable reference with the actual test code, clarify supported URI forms, warn that live tests and examples can leave residual server state, and correct the verified example script commands. Constraint: Existing SDK sync and async tests already consume MORPHIK_TEST_URI and the example script exposes --run-async. Rejected: Supporting both environment variable names in test code | unnecessary behavior change for a documentation mismatch. Confidence: high Scope-risk: narrow Directive: Keep this PR limited to SDK live-test documentation and usage text; do not change live-test behavior. Tested: git diff --check; rg -n -- "MORPHIK_TEST_URL|MORPHIK_TEST_URI|localhost:8000 URL|--async|--run-async" sdks/python/README.md sdks/python/morphik/tests/README.md sdks/python/morphik/tests/example_usage.py sdks/python/morphik/tests/test_sync.py sdks/python/morphik/tests/test_async.py; uv run python -m morphik.tests.example_usage --help; cd sdks/python/morphik/tests && PYTHONPATH=../.. uv run python example_usage.py --help; uv run python -m py_compile sdks/python/morphik/tests/example_usage.py; uv run pytest --collect-only -q sdks/python/morphik/tests/test_sync.py sdks/python/morphik/tests/test_async.py Not-tested: Live SDK test execution against a running Morphik server. --- sdks/python/README.md | 18 ++++++++++---- sdks/python/morphik/tests/README.md | 28 +++++++++++++++------- sdks/python/morphik/tests/example_usage.py | 4 ++-- 3 files changed, 34 insertions(+), 16 deletions(-) diff --git a/sdks/python/README.md b/sdks/python/README.md index 74437406..07ac76d5 100644 --- a/sdks/python/README.md +++ b/sdks/python/README.md @@ -169,6 +169,10 @@ pip install -r test_requirements.txt Then run the tests: +These live tests mutate server state and may leave residual folders or scoped +artifacts behind. Run them only against a local or disposable test server or +tenant, never against production or shared data. + ```bash # Run all tests (requires a running Morphik server) pytest morphik/tests/ -v @@ -180,20 +184,24 @@ pytest morphik/tests/test_async.py -v # Skip tests if you don't have a running server SKIP_LIVE_TESTS=1 pytest morphik/tests/ -v -# Specify a custom server URL for tests -MORPHIK_TEST_URL=http://custom-server:8000 pytest morphik/tests/ -v +# Specify a custom disposable test server URI +# Use direct http(s) endpoints inline; source credential-bearing morphik:// URIs +# from a local secret store or uncommitted env file instead of shell history or CI logs +MORPHIK_TEST_URI=http://custom-server:8000 pytest morphik/tests/ -v ``` ### Example Usage Script -The SDK comes with an example script that demonstrates basic usage: +The SDK comes with an example script that demonstrates basic usage. It creates +server data and only partially cleans it up, so run it only against a local or +disposable test environment. ```bash # Run synchronous example -python -m morphik.tests.example_usage +uv run python -m morphik.tests.example_usage # Run asynchronous example -python -m morphik.tests.example_usage --async +uv run python -m morphik.tests.example_usage --run-async ``` The example script demonstrates: diff --git a/sdks/python/morphik/tests/README.md b/sdks/python/morphik/tests/README.md index ce83960b..ccec875a 100644 --- a/sdks/python/morphik/tests/README.md +++ b/sdks/python/morphik/tests/README.md @@ -15,27 +15,37 @@ This directory contains tests and example code for the Morphik SDK. ## Running Tests +These live tests mutate server state and may leave residual folders or scoped +artifacts behind. Run them only against a local or disposable test server or +tenant, never against production or shared data. + ```bash -# Using default localhost:8000 URL +# Using default localhost:8000 server URI pytest test_sync.py test_async.py -v # Tests connect to localhost:8000 by default -# No need to specify a URL unless you want to test against a different server +# No need to specify a URI unless you want to test against a different server -# With a custom server URL (optional) -MORPHIK_TEST_URL=http://custom-url:8000 pytest test_sync.py -v +# With a custom disposable test server URI (optional; applies to sync and async tests) +# Use direct http(s) endpoints inline; source credential-bearing morphik:// URIs +# from a local secret store or uncommitted env file instead of shell history or CI logs +MORPHIK_TEST_URI=http://custom-url:8000 pytest test_sync.py test_async.py -v ``` ### Example Usage Script + +The example script creates server data and only partially cleans it up. Run it +only against the same local or disposable test environment. + ```bash -# Run synchronous example -python example_usage.py +# Run synchronous example from this directory +PYTHONPATH=../.. uv run python example_usage.py -# Run asynchronous example -python example_usage.py --async +# Run asynchronous example from this directory +PYTHONPATH=../.. uv run python example_usage.py --run-async ``` ## Environment Variables -- `MORPHIK_TEST_URL` - The URL of the Morphik server to use for tests (default: http://localhost:8000) +- `MORPHIK_TEST_URI` - The Morphik server URI to use for tests; accepts direct `http(s)://` endpoints or authenticated `morphik://` URIs (default: http://localhost:8000) - `SKIP_LIVE_TESTS` - Set to "1" to skip tests that require a running server diff --git a/sdks/python/morphik/tests/example_usage.py b/sdks/python/morphik/tests/example_usage.py index aff9f0f1..a5fed5d0 100755 --- a/sdks/python/morphik/tests/example_usage.py +++ b/sdks/python/morphik/tests/example_usage.py @@ -4,10 +4,10 @@ This can be run to verify that the SDK is working correctly. Usage: - python example_usage.py [--async] + uv run python example_usage.py [--run-async] Options: - --async Run the example using the async client + --run-async Run the example using the async client """ import argparse