Expose expires/max_age in Cookies.set

[Garrett-R]

Feature Request

The current signature of Cookies.set could be updated to allow passing in expires. Or even max_age which is a bit more user-friendly.

Use Case

I have this test utility function:

from uuid import UUID
from fastapi.testclient import TestClient

_ONE_DAY_IN_SECONDS = 24 * 60 * 60

def set_cookie_in_test(test_client: TestClient,
                       cookie_key: str,
                       cookie_value: str | UUID,
                       path: str = '/',
                       max_age: int = _ONE_DAY_IN_SECONDS) -> None:
    cookies = test_client.cookies
    cookies.set(
        cookie_key,
        str(cookie_value),
        path=path,
        max_age=max_age,  # Not an accepted arg!
    )
    test_client.cookies = cookies

---

In the meantime, here's a workaround.

[ketpatil77]

For a test cookie with an expiry, use the public underlying CookieJar and the standard-library Cookie object. Cookies.set does not accept max_age on HTTPX 0.28.1:

from http.cookiejar import Cookie
from time import time

def set_expiring_cookie(client, name, value, *, domain, path="/", max_age=86400):
    cookie = Cookie(
        version=0, name=name, value=str(value),
        port=None, port_specified=False,
        domain=domain, domain_specified=False, domain_initial_dot=False,
        path=path, path_specified=True, secure=False,
        expires=int(time()) + max_age, discard=False,
        comment=None, comment_url=None, rest={}, rfc2109=False,
    )
    client.cookies.jar.set_cookie(cookie)

Use a dotted request host such as app.test for domain. For the usual single-label TestClient host testserver, Python CookieJar uses an effective host of testserver.local; passing domain="testserver.local" was verified to send the cookie to http://testserver. This creates a non-secure cookie suitable for HTTP tests; set secure=True for an HTTPS-only cookie. Do not include a scheme or port in domain. CookieJar follows its own cookie policy, so do not assume browser host-only behavior for every subdomain test.

max_age here is converted to an absolute expiry time; this is not sending a Set-Cookie Max-Age attribute. Request Cookie headers contain names/values, not expiry metadata. Expired entries may remain in the jar but are not sent; client.cookies.jar.clear_expired_cookies() removes them. To test your application's actual Set-Cookie semantics, exercising its response and letting the client's cookie extraction run is closer to browser behavior.

Validated future and expired cookies through MockTransport using a dotted test host, including expiry cleanup. stdlib CookieJar, HTTPX cookies.

Validation version: HTTPX 0.28.1, Python 3.11.9.