Add doc on testing #23

i2y · 2025-10-04T05:19:36Z

This PR adds comprehensive testing guide with ASGI/WSGI examples for services, clients, and interceptors.

stefanvanburen

looks good to me — we're being pretty pytest-specific in this doc, but I think that's reasonable given how much the ecosystem seems to prefer it over unittest

stefanvanburen · 2025-10-13T13:57:04Z

docs/testing.md

+            method_name = ctx.method().name
+            self.requests.append(method_name)
+            return method_name
+
+        async def on_end(self, token, ctx):
+            # token is the value returned from on_start
+            pass


do we need to return the method_name / have the comment if we just check self.requests? up to you if you want to keep this in (similar comment for WSGI)

Agree that along the lines of above comments, it's best if we show how to test something real since users will be reading this for advice on that. This LoggingInterceptor doesn't actually log - to make it a testable real interceptor, we'd probably pass in a Logger and mock it or similar. Alternatively, auth interceptor may be easier to demonstrate here

anuraaga

I agree pytest is a de-facto standard and don't think we need to avoid it in the examples. However, I've left some comments in that we probably should minimize actually documenting pytest itself - one reason is that it does end up looking like we basically require pytest for testing connect code which isn't the case.

Perhaps in the very first section Recommended approach: In-memory testing we can add a code snippet with no test infrastructure at all, documenting the most important point of the doc, using the httpx transports to connect a client and server without an app server.

import httpx
from greet_connect import GreetASGIApplication
from server import Greeter

app = GreetASGIApplication(Greeter())
async with httpx.AsyncClient(
  transport=httpx.ASGITransport(app=app),
            base_url="http://test"
        ) as session:
          client = GreetServiceClient("http://test", session=session) # URL is ignored
          response = client.greet(GreetRequest(name="Alice"))
print(response.greeting)

Then add some examples wiring it up to pytest, including some basic example of fixture. But I'd recommend

Keeping "general usage of connect" as much as possible in other docs (we can add what's missing there that we have in this PR)
Minimizing "general usage of pytest" as much as possible. In fact, instead of having many examples of pytest usage, we could instead have our basic example covered in two forms, pytest and unittest

How does that sound?

docs/testing.md

anuraaga · 2025-10-14T01:46:10Z

docs/testing.md

+    from greet.v1.greet_connect import GreetService, GreetServiceASGIApplication, GreetServiceClient
+    from greet.v1.greet_pb2 import GreetRequest, GreetResponse
+
+    class TestGreetService(GreetService):


For the section about testing services, I think we wouldn't have names like TestService - we should be testing the real code here.

I think we can do something like

Testing the service we created in the [Getting Started](./getting-started) guide may look like this:

from greet_connect import GreetASGIApplication from server import Greeter

any real test will be importing the service, not having it defined in the same file

anuraaga · 2025-10-14T01:47:41Z

docs/testing.md

+    @pytest.mark.asyncio
+    async def test_greet():
+        # Create the ASGI application
+        app = GreetServiceASGIApplication(TestGreetService())


We can't show it clearly with our example services, we could consider something like # Initialize your service with mock dependencies as needed. Though maybe we can leave "general testing" advice out of the doc

anuraaga · 2025-10-14T01:50:40Z

docs/testing.md

+        assert response.greeting == "Hello, Alice!"
+
+    @pytest.mark.asyncio
+    async def test_greet_multiple_names(greet_client):


There doesn't seem to be multiple names. How about empty_name and use empty string?

anuraaga · 2025-10-14T01:57:58Z

docs/testing.md

+- Follows pytest best practices
+- Matches the pattern used in connect-python's own test suite
+
+### Testing error handling


After writing below comments, I also thought this overlaps well with errors.md.

anuraaga · 2025-10-14T02:04:44Z

docs/testing.md

+
+    @pytest.mark.asyncio
+    async def test_client_error_handling():
+        class TestGreetService(GreetService):


Is it worth something like # It can be convenient to use a mock such as with pytest mocker?

anuraaga · 2025-10-14T02:07:55Z

docs/testing.md

+            method_name = ctx.method().name
+            self.requests.append(method_name)
+            return method_name
+
+        async def on_end(self, token, ctx):
+            # token is the value returned from on_start
+            pass


Agree that along the lines of above comments, it's best if we show how to test something real since users will be reading this for advice on that. This LoggingInterceptor doesn't actually log - to make it a testable real interceptor, we'd probably pass in a Logger and mock it or similar. Alternatively, auth interceptor may be easier to demonstrate here

anuraaga · 2025-10-14T02:09:48Z

docs/testing.md

+
+### Project structure
+
+Organize your tests in a `test/` directory at the root of your project:


Actually this is something I forgot when reorganizing for this repo - AFAIK, tests is the default for pytest and doesn't require configuration, that's what we should use here.

That being said, this whole section seems more like docs on how to use pytest, rather than testing connect. Maybe we can remove it?

anuraaga · 2025-10-14T02:12:18Z

docs/testing.md

+        async def greet(self, request, ctx):
+            # Check for authorization header
+            auth = ctx.request_headers().get("authorization")
+            if not auth or not auth.startswith("Bearer "):


If we update the interceptor example, we can remove this one, which is good since I think it's very far from any real life service

Co-authored-by: Anuraag (Rag) Agrawal <[email protected]> Signed-off-by: Yasushi Itoh <[email protected]>

Signed-off-by: i2y <[email protected]>

i2y · 2025-10-19T06:38:25Z

@anuraaga @stefanvanburen
Thanks! I've addressed your comments. Could you please review this PR again?

anuraaga

Looks much nicer, thanks!

anuraaga · 2025-10-20T00:49:18Z

docs/testing.md

+
+## Setup
+
+Install httpx for testing connect-python services and clients:


I don't know if we need this, won't it always be installed as a dependency of connect-python?

Thanks for catching that! Fixed in 58d6653.

Signed-off-by: i2y <[email protected]>

i2y added 2 commits October 4, 2025 14:18

Add doc on testing

666bb39

Signed-off-by: i2y <[email protected]>

fix

a29ee46

Signed-off-by: i2y <[email protected]>

i2y force-pushed the docs/add-testing-guide branch from 1f96395 to a29ee46 Compare October 5, 2025 12:18

i2y added 2 commits October 13, 2025 16:44

Merge branch 'main' into docs/add-testing-guide

d8e9f14

fix

0e41b3a

Signed-off-by: i2y <[email protected]>

i2y marked this pull request as ready for review October 13, 2025 08:20

i2y requested review from anuraaga, spenczar and stefanvanburen October 13, 2025 08:20

stefanvanburen approved these changes Oct 13, 2025

View reviewed changes

anuraaga reviewed Oct 14, 2025

View reviewed changes

i2y and others added 8 commits October 19, 2025 13:30

Update docs/testing.md

3cdd3c4

Co-authored-by: Anuraag (Rag) Agrawal <[email protected]> Signed-off-by: Yasushi Itoh <[email protected]>

Update docs/testing.md

b978c40

Co-authored-by: Anuraag (Rag) Agrawal <[email protected]> Signed-off-by: Yasushi Itoh <[email protected]>

Merge branch 'main' into docs/add-testing-guide

b1a34c0

fix

3b47abf

Signed-off-by: i2y <[email protected]>

fix

395a234

Signed-off-by: i2y <[email protected]>

fix

dd04315

Signed-off-by: i2y <[email protected]>

fix

b44bc29

Signed-off-by: i2y <[email protected]>

fix

893a25a

Signed-off-by: i2y <[email protected]>

i2y requested review from anuraaga and stefanvanburen October 19, 2025 06:35

anuraaga approved these changes Oct 20, 2025

View reviewed changes

fix

58d6653

Signed-off-by: i2y <[email protected]>

stefanvanburen approved these changes Oct 20, 2025

View reviewed changes

i2y merged commit 386bddc into main Oct 21, 2025
23 checks passed

i2y deleted the docs/add-testing-guide branch October 21, 2025 03:36


		### Project structure

		Organize your tests in a `test/` directory at the root of your project:


		## Setup

		Install httpx for testing connect-python services and clients:

Add doc on testing #23

Add doc on testing #23

Uh oh!

Conversation

i2y commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefanvanburen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anuraaga left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

i2y commented Oct 19, 2025

Uh oh!

anuraaga left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

i2y commented Oct 4, 2025 •

edited

Loading