From fa38ac68f0085a7e08706d30c29e7fe6b0eb0864 Mon Sep 17 00:00:00 2001
From: bensynapse <118375461+bensynapse@users.noreply.github.com>
Date: Mon, 5 Oct 2026 04:57:46 +0300
Subject: [PATCH 1/2] Preserve empty query values in mapping matchers

---
 doc/howto.rst                                 |  5 +++
 pytest_httpserver/httpserver.py               |  5 ++-
 .../empty-query-values-4e70831a4cba318c.yaml  |  6 +++
 tests/test_querymatcher.py                    | 38 +++++++++++++++++++
 tests/test_querystring.py                     | 22 +++++++++++
 5 files changed, 74 insertions(+), 2 deletions(-)
 create mode 100644 releasenotes/notes/empty-query-values-4e70831a4cba318c.yaml

diff --git a/doc/howto.rst b/doc/howto.rst
index d3226717..d726ca36 100644
--- a/doc/howto.rst
+++ b/doc/howto.rst
@@ -48,6 +48,11 @@ query string as a dictionary.
 
 Behind the scenes an additional step is done by the library: it parses up the
 query_string into the dict and then compares it with the dict provided.
+Empty values are preserved. For example, ``query_string={"flag": ""}`` matches
+both ``?flag=`` and ``?flag``. Neither matches an empty dictionary.
+If a parameter appears more than once, a dictionary matches its first value,
+including an empty value. A ``werkzeug.datastructures.MultiDict`` matches all
+values, including empty ones.
 
 
 URI matching
diff --git a/pytest_httpserver/httpserver.py b/pytest_httpserver/httpserver.py
index 00ca6131..29191643 100644
--- a/pytest_httpserver/httpserver.py
+++ b/pytest_httpserver/httpserver.py
@@ -234,12 +234,13 @@ def __init__(self, query_dict: Mapping[str, str] | MultiDict[str, str]) -> None:
             key-value mapping where both key and value should be string. If there are multiple
             values specified for the same key in the request, the first element will be used.
             If you want to match multiple values, use a MultiDict object from werkzeug, which
-            represents multiple values for one key.
+            represents multiple values for one key. Empty values are kept, including
+            parameters without an equals sign. An empty value is distinct from a missing key.
         """
         self.query_dict = query_dict
 
     def get_comparing_values(self, request_query_string: bytes) -> tuple[Mapping[str, str], Mapping[str, str]]:
-        query = MultiDict(urllib.parse.parse_qsl(request_query_string.decode("utf-8")))
+        query = MultiDict(urllib.parse.parse_qsl(request_query_string.decode("utf-8"), keep_blank_values=True))
         if isinstance(self.query_dict, MultiDict):
             return (query, self.query_dict)
         else:
diff --git a/releasenotes/notes/empty-query-values-4e70831a4cba318c.yaml b/releasenotes/notes/empty-query-values-4e70831a4cba318c.yaml
new file mode 100644
index 00000000..fbf53165
--- /dev/null
+++ b/releasenotes/notes/empty-query-values-4e70831a4cba318c.yaml
@@ -0,0 +1,6 @@
+fixes:
+  - |
+    Preserve empty query values when matching dictionaries and MultiDict objects.
+    Both ``flag=`` and ``flag`` match ``{"flag": ""}`` and no longer match ``{}``.
+    For repeated parameters, dictionary matching uses the first value even when it
+    is empty. MultiDict matching includes every empty value.
diff --git a/tests/test_querymatcher.py b/tests/test_querymatcher.py
index d7752f5b..c64799bb 100644
--- a/tests/test_querymatcher.py
+++ b/tests/test_querymatcher.py
@@ -1,3 +1,4 @@
+import pytest
 from werkzeug.datastructures import MultiDict
 
 from pytest_httpserver.httpserver import BooleanQueryMatcher
@@ -55,3 +56,40 @@ def test_qm_mapping_multiple_values():
     md = MultiDict([("k1", "v1"), ("k1", "v2")])
     qm = MappingQueryMatcher(md)
     assert_match(qm, b"k1=v1&k1=v2")
+
+
+@pytest.mark.parametrize("query_string", [b"flag=", b"flag", b"flag=&", b"&flag="])
+def test_qm_mapping_empty_value(query_string):
+    qm = MappingQueryMatcher({"flag": ""})
+    assert_match(qm, query_string)
+    assert_not_match(qm, b"")
+    assert_not_match(qm, b"flag=value")
+
+
+@pytest.mark.parametrize("query_string", [b"flag=", b"flag", b"flag=&flag="])
+def test_qm_mapping_empty_value_is_not_missing(query_string):
+    qm = MappingQueryMatcher({})
+    assert_not_match(qm, query_string)
+    assert_match(qm, b"")
+
+
+@pytest.mark.parametrize("query_string", [b"flag=&flag=value", b"flag&flag=value"])
+def test_qm_mapping_first_value_is_empty(query_string):
+    assert_match(MappingQueryMatcher({"flag": ""}), query_string)
+    assert_not_match(MappingQueryMatcher({"flag": "value"}), query_string)
+    assert_match(MappingQueryMatcher({"flag": "value"}), b"flag=value&flag=")
+
+
+@pytest.mark.parametrize("query_string", [b"flag=&flag=value", b"flag&flag=value"])
+def test_qm_mapping_multiple_values_include_empty(query_string):
+    qm = MappingQueryMatcher(MultiDict([("flag", ""), ("flag", "value")]))
+    assert_match(qm, query_string)
+    assert_not_match(qm, b"flag=value")
+    assert_not_match(qm, b"flag=")
+
+
+def test_qm_mapping_empty_encoded_name():
+    qm = MappingQueryMatcher({"empty name": "", "": "value"})
+    assert_match(qm, b"empty%20name=&=value")
+    assert_match(qm, b"=value&empty+name=")
+    assert_not_match(qm, b"=value")
diff --git a/tests/test_querystring.py b/tests/test_querystring.py
index ff3bd997..4497f4d5 100644
--- a/tests/test_querystring.py
+++ b/tests/test_querystring.py
@@ -1,4 +1,6 @@
+import pytest
 import requests
+from werkzeug.datastructures import MultiDict
 
 from pytest_httpserver import HTTPServer
 
@@ -32,3 +34,23 @@ def test_querystring_dict(httpserver: HTTPServer):
     httpserver.check_assertions()
     assert response.text == "example_response"
     assert response.status_code == 200
+
+
+@pytest.mark.parametrize("query_string", [{"flag": ""}, MultiDict([("flag", ""), ("flag", "value")])])
+def test_querystring_empty_value(httpserver: HTTPServer, query_string):
+    httpserver.expect_request("/foobar", query_string=query_string).respond_with_data("example_response")
+    response = requests.get(
+        httpserver.url_for("/foobar"),
+        params=query_string.items(multi=True) if isinstance(query_string, MultiDict) else query_string,
+    )
+    httpserver.check_assertions()
+    assert response.status_code == 200
+    assert response.text == "example_response"
+
+
+def test_querystring_empty_value_does_not_match_missing(httpserver: HTTPServer):
+    httpserver.expect_request("/foobar", query_string={}).respond_with_data("example_response")
+    response = requests.get(httpserver.url_for("/foobar"), params={"flag": ""})
+    assert response.status_code == 500
+    with pytest.raises(AssertionError, match="No handler found"):
+        httpserver.check_assertions()

From c53fe473a91b0c96bb37fe506f966b7e28968002 Mon Sep 17 00:00:00 2001
From: bensynapse <118375461+bensynapse@users.noreply.github.com>
Date: Mon, 5 Oct 2026 08:50:56 +0300
Subject: [PATCH 2/2] Document empty query matching compatibility

---
 .../notes/empty-query-values-4e70831a4cba318c.yaml  |  5 +++++
 tests/test_querystring.py                           | 13 +++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/releasenotes/notes/empty-query-values-4e70831a4cba318c.yaml b/releasenotes/notes/empty-query-values-4e70831a4cba318c.yaml
index fbf53165..332449cc 100644
--- a/releasenotes/notes/empty-query-values-4e70831a4cba318c.yaml
+++ b/releasenotes/notes/empty-query-values-4e70831a4cba318c.yaml
@@ -4,3 +4,8 @@ fixes:
     Both ``flag=`` and ``flag`` match ``{"flag": ""}`` and no longer match ``{}``.
     For repeated parameters, dictionary matching uses the first value even when it
     is empty. MultiDict matching includes every empty value.
+upgrade:
+  - |
+    Dictionary expectations must include parameters with empty values.
+    A request for ``flag=&foo=123`` previously matched ``{"foo": "123"}``.
+    It now requires ``{"flag": "", "foo": "123"}``.
diff --git a/tests/test_querystring.py b/tests/test_querystring.py
index 4497f4d5..fc8f56c2 100644
--- a/tests/test_querystring.py
+++ b/tests/test_querystring.py
@@ -54,3 +54,16 @@ def test_querystring_empty_value_does_not_match_missing(httpserver: HTTPServer):
     assert response.status_code == 500
     with pytest.raises(AssertionError, match="No handler found"):
         httpserver.check_assertions()
+
+
+@pytest.mark.xfail(
+    strict=True,
+    raises=AssertionError,
+    reason="Blank query values must be included in the expected dictionary",
+)
+def test_querystring_dict_ignores_empty_value(httpserver: HTTPServer):
+    httpserver.expect_request("/foobar", query_string={"foo": "123"}).respond_with_data("example_response")
+    response = requests.get(httpserver.url_for("/foobar?flag=&foo=123"))
+    httpserver.check_assertions()
+    assert response.status_code == 200
+    assert response.text == "example_response"