From 7804e32a9b8f9e23720fa5581787ed2ff3167da4 Mon Sep 17 00:00:00 2001
From: Mikhail Schukin <misha2002mg@gmail.com>
Date: Tue, 5 May 2026 14:52:50 +0300
Subject: [PATCH] feat: Add task-scoped kwargs key/value filtering to task
 search

- extend task search query with `task_name`, `arg_key`, `arg_value`
- add dynamic task key options endpoint for selected task name
- apply key/value filtering in repository for both Postgres and SQLite
- preserve filter state through HTMX updates, sorting links, and infinite scroll
---
 taskiq_dashboard/api/routers/task.py          |  68 +++++++-
 taskiq_dashboard/api/templates/home.html      | 143 +++++++++++++++-
 .../templates/partial/arg_key_options.html    |   6 +
 .../api/templates/partial/task_list.html      |   4 +-
 taskiq_dashboard/domain/repositories/task.py  |  16 ++
 .../infrastructure/repositories/task.py       |  67 +++++++-
 tests/integration/test_task_service.py        | 157 ++++++++++++++++++
 tests/unit/test_task_router_filters.py        | 105 ++++++++++++
 tests/unit/test_task_service_sqlite.py        | 152 +++++++++++++++++
 9 files changed, 709 insertions(+), 9 deletions(-)
 create mode 100644 taskiq_dashboard/api/templates/partial/arg_key_options.html
 create mode 100644 tests/unit/test_task_router_filters.py
 create mode 100644 tests/unit/test_task_service_sqlite.py

diff --git a/taskiq_dashboard/api/routers/task.py b/taskiq_dashboard/api/routers/task.py
index 7ff41d3..754f9a3 100644
--- a/taskiq_dashboard/api/routers/task.py
+++ b/taskiq_dashboard/api/routers/task.py
@@ -22,6 +22,9 @@
 
 class TaskFilter(pydantic.BaseModel):
     q: str = ''
+    task_name: str = ''
+    arg_key: str = ''
+    arg_value: str = ''
     status: TaskStatus | None = None
     limit: int = 30
     offset: int = 0
@@ -63,33 +66,94 @@ async def search_tasks(
     query: tp.Annotated[TaskFilter, fastapi.Query(...)],
     hx_request: tp.Annotated[bool, fastapi.Header(description='Request from htmx')] = False,  # noqa: FBT002
 ) -> HTMLResponse:
+    normalized_task_name = query.task_name.strip()
+    normalized_arg_value = query.arg_value.strip()
+    normalized_arg_key = query.arg_key.strip() if normalized_task_name and normalized_arg_value else ''
+    if not normalized_task_name:
+        normalized_arg_value = ''
     tasks = await repository.find_tasks(
         name=query.q,
+        task_name=normalized_task_name,
+        arg_key=normalized_arg_key,
+        arg_value=normalized_arg_value,
         status=query.status,
         limit=query.limit,
         offset=query.offset,
         sort_by=query.sort_by,
         sort_order=query.sort_order,
     )
+    keys: list[str] = []
+    task_names: list[str] = []
+    if not hx_request:
+        keys = await repository.find_argument_keys(task_name=normalized_task_name)
+        task_names = await repository.find_task_names()
+
     headers: dict[str, str] = {}
     template_name = 'home.html'
     if hx_request:
+        query_params = query.model_dump(exclude={'limit', 'offset'})
+        query_params.update(
+            {
+                'task_name': normalized_task_name,
+                'arg_key': normalized_arg_key,
+                'arg_value': normalized_arg_value,
+            }
+        )
         headers = {
-            'HX-Push-Url': '/?' + urlencode(query.model_dump(exclude={'limit', 'offset'})),
+            'HX-Push-Url': '/?' + urlencode(query_params),
         }
         template_name = 'partial/task_list.html'
+    template_context = query.model_dump()
+    template_context.update(
+        {
+            'task_name': normalized_task_name,
+            'arg_key': normalized_arg_key,
+            'arg_value': normalized_arg_value,
+        }
+    )
+
     return jinja_templates.TemplateResponse(
         request,
         template_name,
         {
             'request': request,
             'results': [task.model_dump() for task in tasks],
-            **query.model_dump(),
+            'keys': keys,
+            'selected_arg_key': normalized_arg_key,
+            'task_names': task_names,
+            **template_context,
         },
         headers=headers,
     )
 
 
+@router.get(
+    '/filters/arg-keys',
+    name='Task argument key options',
+    response_class=HTMLResponse,
+)
+async def argument_key_options(
+    request: fastapi.Request,
+    repository: dishka_fastapi.FromDishka[AbstractTaskRepository],
+    task_name: str = '',
+    arg_key: str = '',
+) -> HTMLResponse:
+    normalized_task_name = task_name.strip()
+    normalized_arg_key = arg_key.strip()
+    keys = await repository.find_argument_keys(task_name=normalized_task_name)
+    if normalized_arg_key not in keys:
+        normalized_arg_key = ''
+    return jinja_templates.TemplateResponse(
+        request,
+        'partial/arg_key_options.html',
+        {
+            'request': request,
+            'keys': keys,
+            'selected_arg_key': normalized_arg_key,
+        },
+    )
+
+
 @router.get(
     '/tasks/{task_id:uuid}',
     name='Task details view',
diff --git a/taskiq_dashboard/api/templates/home.html b/taskiq_dashboard/api/templates/home.html
index 5f209d4..53771b2 100644
--- a/taskiq_dashboard/api/templates/home.html
+++ b/taskiq_dashboard/api/templates/home.html
@@ -30,7 +30,7 @@
                         hx-trigger="keyup changed delay:500ms"
                         hx-target="#task-list-body"
                         hx-push-url="true"
-                        hx-include="[name='status']"
+                        hx-include="[name='status'], [name='task_name'], [name='arg_key'], [name='arg_value']"
                     >
                     <div id="search-slash-hint"
                          class="absolute right-4 top-1/2 -translate-y-1/2 w-5 h-5 text-center leading-5 text-xs rounded-sm bg-ctp-lavender/10 pointer-events-none"
@@ -51,6 +51,83 @@
                     </script>
                 </div>
 
+                <!-- Task Name Filter -->
+                <div class="relative group text-ctp-subtext0 hover:text-ctp-subtext1 focus:text-ctp-subtext1 md:w-auto min-w-[200px]">
+                    <select
+                        name="task_name"
+                        id="task-name-select"
+                        class="w-full px-4 py-2 border rounded focus:outline-none focus:ring-2 transition-all duration-200 hover:shadow-md border-ctp-subtext0 group-hover:border-ctp-subtext1 appearance-none"
+                        hx-get="{{ url_for('Task list view') }}"
+                        hx-trigger="change"
+                        hx-target="#task-list-body"
+                        hx-push-url="true"
+                        hx-include="[name='q'], [name='status']"
+                        hx-vals='js:{arg_key:"", arg_value:""}'
+                    >
+                        {% set selected_task_name = task_name if task_name is defined else '' %}
+                        <option class="bg-ctp-base" value="" {% if not selected_task_name %}selected{% endif %}>
+                            Select task name
+                        </option>
+                        {% for available_task_name in task_names|default([]) %}
+                            <option
+                                class="bg-ctp-base"
+                                value="{{ available_task_name }}"
+                                {% if selected_task_name == available_task_name %}selected{% endif %}
+                            >
+                                {{ available_task_name }}
+                            </option>
+                        {% endfor %}
+                    </select>
+                </div>
+
+                <!-- Argument Key Filter -->
+                <div
+                    id="arg-key-container"
+                    class="relative group text-ctp-subtext0 hover:text-ctp-subtext1 focus:text-ctp-subtext1 md:w-auto min-w-[180px] {% if not task_name %}hidden{% endif %}"
+                >
+                    <select
+                        id="arg-key-select"
+                        name="arg_key"
+                        class="w-full px-4 py-2 border rounded focus:outline-none focus:ring-2 transition-all duration-200 hover:shadow-md border-ctp-subtext0 group-hover:border-ctp-subtext1 appearance-none"
+                        {% if not task_name %}disabled{% endif %}
+                    >
+                        {% set keys = keys if keys is defined else [] %}
+                        {% set selected_arg_key = arg_key if arg_key is defined else '' %}
+                        {% include "partial/arg_key_options.html" with context %}
+                    </select>
+                </div>
+
+                <!-- Argument Value Filter -->
+                <div
+                    id="arg-value-container"
+                    class="relative group text-ctp-subtext0 hover:text-ctp-subtext1 focus:text-ctp-subtext1 md:w-auto min-w-[200px] {% if not arg_key %}hidden{% endif %}"
+                >
+                    <input
+                        type="text"
+                        name="arg_value"
+                        id="arg-value-search"
+                        class="w-full px-4 py-2 border rounded focus:outline-none focus:ring-2 transition-all duration-200 hover:shadow-md border-ctp-subtext0 group-hover:border-ctp-subtext1"
+                        placeholder="Argument value"
+                        value="{{ arg_value if arg_value is defined else '' }}"
+                        hx-get="{{ url_for('Task list view') }}"
+                        hx-trigger="keyup changed delay:500ms"
+                        hx-target="#task-list-body"
+                        hx-push-url="true"
+                        hx-include="[name='q'], [name='status'], [name='task_name']"
+                        hx-vals='js:{arg_key: (document.getElementById("arg-value-search").value.trim() && document.getElementById("arg-key-select").value) ? document.getElementById("arg-key-select").value : ""}'
+                        {% if not arg_key %}disabled{% endif %}
+                    >
+                </div>
+
+                <div
+                    id="arg-key-loader"
+                    hx-get="{{ url_for('Task argument key options') }}"
+                    hx-trigger="load, change from:#task-name-select"
+                    hx-include="[name='task_name'], [name='arg_key']"
+                    hx-target="#arg-key-select"
+                    hx-swap="innerHTML"
+                ></div>
+
                 <!-- Status Filter -->
                 <div class="text-ctp-subtext0 hover:text-ctp-subtext1 focus:text-ctp-subtext1 md:w-auto min-w-[150px]">
                     <div class="relative">
@@ -62,7 +139,7 @@
                         hx-trigger="change"
                         hx-target="#task-list-body"
                         hx-push-url="true"
-                        hx-include="[name='q']"
+                        hx-include="[name='q'], [name='task_name'], [name='arg_key'], [name='arg_value']"
                     >
                         {% set status = status if status is defined else "all" %}
                         <option class="bg-ctp-base" value="null" {% if status == "null" %}selected{% endif %}>All Statuses</option>
@@ -158,7 +235,7 @@
                     <th scope="col" class="px-6 py-3 text-left font-normal text-ctp-text tracking-wider">Status</th>
                     <th scope="col" class="px-6 py-3 text-left font-normal text-ctp-text tracking-wider">Worker</th>
                     <th scope="col" class="px-6 py-3 text-left font-normal text-ctp-text tracking-wider">
-                        <a href="{{ url_for('Task list view') }}?status={{ status }}&q={{ q }}&sort_by=started_at&sort_order={%- if sort_by == 'started_at' and sort_order == 'asc' -%}desc{%- else -%}asc{%- endif -%}"
+                        <a href="{{ url_for('Task list view') }}?status={{ status }}&q={{ q }}&task_name={{ task_name }}&arg_key={{ arg_key }}&arg_value={{ arg_value }}&sort_by=started_at&sort_order={%- if sort_by == 'started_at' and sort_order == 'asc' -%}desc{%- else -%}asc{%- endif -%}"
                            class="flex items-center gap-2 hover:text-ctp-subtext0 transition-colors">
                             Started At
                             <span class="inline-flex">
@@ -175,7 +252,7 @@
                         </a>
                     </th>
                     <th scope="col" class="px-6 py-3 text-left font-normal text-ctp-text tracking-wider">
-                        <a href="{{ url_for('Task list view') }}?status={{ status }}&q={{ q }}&sort_by=finished_at&sort_order={%- if sort_by == 'finished_at' and sort_order == 'asc' -%}desc{%- else -%}asc{%- endif -%}"
+                        <a href="{{ url_for('Task list view') }}?status={{ status }}&q={{ q }}&task_name={{ task_name }}&arg_key={{ arg_key }}&arg_value={{ arg_value }}&sort_by=finished_at&sort_order={%- if sort_by == 'finished_at' and sort_order == 'asc' -%}desc{%- else -%}asc{%- endif -%}"
                            class="flex items-center gap-2 hover:text-ctp-subtext0 transition-colors">
                             Finished At
                             <span class="inline-flex">
@@ -203,6 +280,64 @@
     <!-- Notification container -->
     <div id="notification-list" class="fixed bottom-6 right-6 flex flex-col gap-3 w-fit"></div>
 
+    <script>
+        (function() {
+            const taskNameSelect = document.getElementById('task-name-select');
+            const argKeyContainer = document.getElementById('arg-key-container');
+            const argKeySelect = document.getElementById('arg-key-select');
+            const argValueContainer = document.getElementById('arg-value-container');
+            const argValueInput = document.getElementById('arg-value-search');
+            if (!taskNameSelect || !argKeyContainer || !argKeySelect || !argValueContainer || !argValueInput) {
+                return;
+            }
+
+            function syncFilterState() {
+                const hasTaskName = taskNameSelect.value.trim() !== '';
+                if (!hasTaskName) {
+                    argKeySelect.value = '';
+                    argValueInput.value = '';
+                }
+                const hasArgKey = hasTaskName && argKeySelect.value.trim() !== '';
+                if (!hasArgKey) {
+                    argValueInput.value = '';
+                }
+                const hasArgValue = hasArgKey && argValueInput.value.trim() !== '';
+
+                argKeyContainer.classList.toggle('hidden', !hasTaskName);
+                argKeySelect.disabled = !hasTaskName;
+                argValueContainer.classList.toggle('hidden', !hasArgKey);
+                argValueInput.disabled = !hasArgKey;
+
+                if (hasArgValue) {
+                    argKeySelect.name = 'arg_key';
+                } else {
+                    argKeySelect.removeAttribute('name');
+                }
+            }
+
+            taskNameSelect.addEventListener('change', () => {
+                argKeySelect.value = '';
+                argValueInput.value = '';
+                syncFilterState();
+            });
+
+            argKeySelect.addEventListener('change', () => {
+                argValueInput.value = '';
+                syncFilterState();
+            });
+
+            argValueInput.addEventListener('input', syncFilterState);
+
+            document.body.addEventListener('htmx:afterSwap', (event) => {
+                if (event.detail.target.id === 'arg-key-select') {
+                    syncFilterState();
+                }
+            });
+
+            syncFilterState();
+        })();
+    </script>
+
     <script>
         // Bulk actions management
         (function() {
diff --git a/taskiq_dashboard/api/templates/partial/arg_key_options.html b/taskiq_dashboard/api/templates/partial/arg_key_options.html
new file mode 100644
index 0000000..968f845
--- /dev/null
+++ b/taskiq_dashboard/api/templates/partial/arg_key_options.html
@@ -0,0 +1,6 @@
+<option class="bg-ctp-base" value="" {% if not selected_arg_key %}selected{% endif %}>None</option>
+{% for key in keys %}
+    <option class="bg-ctp-base" value="{{ key }}" {% if selected_arg_key == key %}selected{% endif %}>
+        {{ key }}
+    </option>
+{% endfor %}
diff --git a/taskiq_dashboard/api/templates/partial/task_list.html b/taskiq_dashboard/api/templates/partial/task_list.html
index f55a360..9c4d680 100644
--- a/taskiq_dashboard/api/templates/partial/task_list.html
+++ b/taskiq_dashboard/api/templates/partial/task_list.html
@@ -5,7 +5,7 @@
 {% if not results %}
     <tr>
         <td colspan="7" class="px-6 pt-20 pb-16 text-center text-ctp-subtext0">
-            {% if q or status != 'null' %}
+            {% if q or task_name or arg_key or arg_value or status != 'null' %}
                 No tasks for this filters
             {% else %}
                 No tasks created yet
@@ -19,7 +19,7 @@
 {% set _next_offset = _offset + results|length %}
 {% if results|length >= _limit %}
     <tr class="infinite-sentinel"
-        hx-get="{{ url_for('Task list view') }}?status={{ status }}&q={{ q }}&sort_by={{ sort_by }}&sort_order={{ sort_order }}&limit={{ _limit }}&offset={{ _next_offset }}"
+        hx-get="{{ url_for('Task list view') }}?status={{ status }}&q={{ q }}&task_name={{ task_name }}&arg_key={{ arg_key }}&arg_value={{ arg_value }}&sort_by={{ sort_by }}&sort_order={{ sort_order }}&limit={{ _limit }}&offset={{ _next_offset }}"
         hx-trigger="revealed"
         hx-swap="beforeend"
         hx-target="#task-list-body"></tr>
diff --git a/taskiq_dashboard/domain/repositories/task.py b/taskiq_dashboard/domain/repositories/task.py
index fe92014..7dfbf6b 100644
--- a/taskiq_dashboard/domain/repositories/task.py
+++ b/taskiq_dashboard/domain/repositories/task.py
@@ -7,10 +7,18 @@
 
 
 class AbstractTaskRepository(ABC):
+    @abstractmethod
+    async def find_task_names(self) -> list[str]:
+        """Return distinct task names available for filtering."""
+        ...
+
     @abstractmethod
     async def find_tasks(  # noqa: PLR0913
         self,
         name: str | None = None,
+        task_name: str | None = None,
+        arg_key: str | None = None,
+        arg_value: str | None = None,
         status: TaskStatus | None = None,
         sort_by: tp.Literal['started_at', 'finished_at'] | None = None,
         sort_order: tp.Literal['asc', 'desc'] = 'desc',
@@ -23,6 +31,9 @@ async def find_tasks(  # noqa: PLR0913
         Args:
             status: Filter by task status
             name: Filter by task name (fuzzy search)
+            task_name: Exact task name filter
+            arg_key: Task argument key to search
+            arg_value: Task argument value for selected key
             sort_by: Column to sort by ('started_at' or 'finished_at')
             sort_order: Sort order ('asc' or 'desc')
             limit: Number of tasks to retrieve
@@ -33,6 +44,11 @@ async def find_tasks(  # noqa: PLR0913
         """
         ...
 
+    @abstractmethod
+    async def find_argument_keys(self, task_name: str | None = None) -> list[str]:
+        """Return available kwargs keys for selected task."""
+        ...
+
     @abstractmethod
     async def get_task_by_id(self, task_id: uuid.UUID) -> Task | None:
         """Retrieve a specific task by ID."""
diff --git a/taskiq_dashboard/infrastructure/repositories/task.py b/taskiq_dashboard/infrastructure/repositories/task.py
index 5a26ed8..5e729ed 100644
--- a/taskiq_dashboard/infrastructure/repositories/task.py
+++ b/taskiq_dashboard/infrastructure/repositories/task.py
@@ -21,9 +21,23 @@ def __init__(
         self._session_provider = session_provider
         self.task = task_model
 
+    async def find_task_names(self) -> list[str]:
+        query = (
+            sa.select(sa.distinct(self.task.name))
+            .where(self.task.name.is_not(None))
+            .where(self.task.name != '')
+            .order_by(self.task.name.asc())
+        )
+        async with self._session_provider.session() as session:
+            rows = (await session.execute(query)).scalars().all()
+        return [name for name in rows if isinstance(name, str) and name]
+
     async def find_tasks(  # noqa: PLR0913
         self,
         name: str | None = None,
+        task_name: str | None = None,
+        arg_key: str | None = None,
+        arg_value: str | None = None,
         status: TaskStatus | None = None,
         sort_by: tp.Literal['started_at', 'finished_at'] | None = None,
         sort_order: tp.Literal['asc', 'desc'] = 'desc',
@@ -40,6 +54,20 @@ async def find_tasks(  # noqa: PLR0913
                     id_text.ilike(search_pattern)
                 )
             )
+        normalized_task_name = task_name.strip() if task_name else ''
+        if normalized_task_name:
+            query = query.where(self.task.name == normalized_task_name)
+
+        normalized_arg_key = arg_key.strip() if arg_key else ''
+        normalized_arg_value = arg_value.strip() if arg_value else ''
+        if normalized_task_name and normalized_arg_key and normalized_arg_value:
+            if self.task is PostgresTask:
+                kwargs_condition = self.task.kwargs[normalized_arg_key].astext == normalized_arg_value
+            else:
+                kwargs_condition = (
+                    sa.func.json_extract(self.task.kwargs, f'$.{normalized_arg_key}') == normalized_arg_value
+                )
+            query = query.where(kwargs_condition)
         if status is not None:
             query = query.where(self.task.status == status.value)
         if sort_by:
@@ -48,7 +76,8 @@ async def find_tasks(  # noqa: PLR0913
             elif sort_by == 'started_at':
                 sort_column = self.task.started_at
             else:
-                raise ValueError('Unsupported sort_by value: %s', sort_by)
+                message = f'Unsupported sort_by value: {sort_by}'
+                raise ValueError(message)
             query = query.order_by(sort_column.asc()) if sort_order == 'asc' else query.order_by(sort_column.desc())
         query = query.limit(limit).offset(offset)
         async with self._session_provider.session() as session:
@@ -56,6 +85,42 @@ async def find_tasks(  # noqa: PLR0913
             task_schemas = result.scalars().all()
         return [Task.model_validate(task) for task in task_schemas]
 
+    async def find_argument_keys(self, task_name: str | None = None) -> list[str]:
+        normalized_task_name = task_name.strip() if task_name else ''
+        if not normalized_task_name:
+            return []
+
+        if self.task is PostgresTask:
+            keys_subquery = (
+                sa.select(
+                    sa.func.jsonb_object_keys(self.task.kwargs).label('key'),
+                )
+                .where(self.task.name == normalized_task_name)
+                .subquery()
+            )
+            query = (
+                sa.select(sa.distinct(keys_subquery.c.key))
+                .where(keys_subquery.c.key.is_not(None))
+                .where(keys_subquery.c.key != '')
+                .order_by(keys_subquery.c.key.asc())
+            )
+        else:
+            json_each = sa.func.json_each(self.task.kwargs).table_valued('key', 'value').alias('json_each')
+            query = (
+                sa.select(sa.distinct(json_each.c.key))
+                .select_from(self.task)
+                .join(json_each, sa.true())
+                .where(self.task.name == normalized_task_name)
+                .where(json_each.c.key.is_not(None))
+                .where(json_each.c.key != '')
+                .order_by(json_each.c.key.asc())
+            )
+
+        async with self._session_provider.session() as session:
+            rows = (await session.execute(query)).scalars().all()
+
+        return [str(key) for key in rows if isinstance(key, str)]
+
     async def get_task_by_id(self, task_id: uuid.UUID) -> Task | None:
         query = sa.select(self.task).where(self.task.id == task_id)
         async with self._session_provider.session() as session:
diff --git a/tests/integration/test_task_service.py b/tests/integration/test_task_service.py
index 1bd69c8..ee26f8b 100644
--- a/tests/integration/test_task_service.py
+++ b/tests/integration/test_task_service.py
@@ -252,6 +252,163 @@ async def test_when_finding_tasks_with_id_search__then_return_matching_tasks(
         assert len(tasks) == 1
         assert tasks[0].id == known_task_id
 
+    async def test_when_filtering_by_task_name__then_return_only_selected_task(
+        self,
+        task_service: AbstractTaskRepository,
+    ) -> None:
+        # Given
+        await PostgresTaskFactory.create_async(name='task_one')
+        await PostgresTaskFactory.create_async(name='task_two')
+
+        # When
+        tasks = await task_service.find_tasks(task_name='task_one')
+
+        # Then
+        assert len(tasks) == 1
+        assert tasks[0].name == 'task_one'
+
+    async def test_when_filtering_by_arg_key_value__then_match_only_kwargs_for_selected_task(
+        self,
+        task_service: AbstractTaskRepository,
+    ) -> None:
+        # Given
+        await PostgresTaskFactory.create_async(
+            name='task_one',
+            args=['legacy-only'],
+            kwargs={'comment': 'first payload', 'entity_id': 'A-100'},
+        )
+        await PostgresTaskFactory.create_async(
+            name='task_one',
+            args=[],
+            kwargs={'entity_id': 'A-200', 'operation': 'update', 'actor': 'worker-2'},
+        )
+        await PostgresTaskFactory.create_async(
+            name='task_two',
+            args=[],
+            kwargs={'external_id': 'EXT-1001'},
+        )
+
+        # When
+        first_match = await task_service.find_tasks(
+            task_name='task_one',
+            arg_key='entity_id',
+            arg_value='A-100',
+        )
+        second_match = await task_service.find_tasks(
+            task_name='task_one',
+            arg_key='entity_id',
+            arg_value='A-200',
+        )
+
+        # Then
+        assert len(first_match) == 1
+        assert first_match[0].kwargs.get('entity_id') == 'A-100'
+        assert len(second_match) == 1
+        assert second_match[0].kwargs.get('entity_id') == 'A-200'
+
+    async def test_when_filtering_by_arg_key_without_value__then_arg_filter_is_not_applied(
+        self,
+        task_service: AbstractTaskRepository,
+    ) -> None:
+        # Given
+        await PostgresTaskFactory.create_async(
+            name='task_one',
+            kwargs={'entity_id': 'A-111'},
+        )
+        await PostgresTaskFactory.create_async(
+            name='task_one',
+            kwargs={'entity_id': 'A-222'},
+        )
+
+        # When
+        tasks = await task_service.find_tasks(
+            task_name='task_one',
+            arg_key='entity_id',
+            arg_value='',
+        )
+
+        # Then
+        assert len(tasks) == 2
+
+    async def test_when_filtering_by_arg_key_value_without_task_name__then_arg_filter_is_not_applied(
+        self,
+        task_service: AbstractTaskRepository,
+    ) -> None:
+        # Given
+        await PostgresTaskFactory.create_async(
+            name='task_one',
+            kwargs={'entity_id': 'A-111'},
+        )
+        await PostgresTaskFactory.create_async(
+            name='task_two',
+            kwargs={'entity_id': 'A-222'},
+        )
+
+        # When
+        tasks = await task_service.find_tasks(
+            task_name='',
+            arg_key='entity_id',
+            arg_value='A-111',
+        )
+
+        # Then
+        assert len(tasks) == 2
+
+    async def test_when_requesting_argument_keys_for_selected_task__then_return_actual_keys(
+        self,
+        task_service: AbstractTaskRepository,
+    ) -> None:
+        # Given
+        await PostgresTaskFactory.create_async(
+            name='task_one',
+            kwargs={'entity_id': 'A-111', 'operation': 'create'},
+        )
+        await PostgresTaskFactory.create_async(
+            name='task_two',
+            kwargs={'external_id': 'EXT-1001', 'priority': 'high'},
+        )
+
+        # When
+        request_action_keys = await task_service.find_argument_keys(task_name='task_one')
+        external_task_keys = await task_service.find_argument_keys(task_name='task_two')
+
+        # Then
+        assert 'entity_id' in request_action_keys
+        assert 'operation' in request_action_keys
+        assert 'external_id' not in request_action_keys
+        assert set(external_task_keys) == {'external_id', 'priority'}
+
+    async def test_when_requesting_argument_keys_without_task_name__then_return_empty_list(
+        self,
+        task_service: AbstractTaskRepository,
+    ) -> None:
+        # Given
+        await PostgresTaskFactory.create_async(
+            name='task_one',
+            kwargs={'entity_id': 'A-111', 'operation': 'create'},
+        )
+
+        # When
+        all_keys = await task_service.find_argument_keys()
+
+        # Then
+        assert all_keys == []
+
+    async def test_when_requesting_task_name_options__then_return_distinct_sorted_names(
+        self,
+        task_service: AbstractTaskRepository,
+    ) -> None:
+        # Given
+        await PostgresTaskFactory.create_async(name='task_two')
+        await PostgresTaskFactory.create_async(name='task_one')
+        await PostgresTaskFactory.create_async(name='task_one')
+
+        # When
+        task_names = await task_service.find_task_names()
+
+        # Then
+        assert task_names == ['task_one', 'task_two']
+
     async def test_when_finding_tasks_with_pagination__then_return_correct_page(
         self,
         task_service: AbstractTaskRepository,
diff --git a/tests/unit/test_task_router_filters.py b/tests/unit/test_task_router_filters.py
new file mode 100644
index 0000000..9688cff
--- /dev/null
+++ b/tests/unit/test_task_router_filters.py
@@ -0,0 +1,105 @@
+import uuid
+from unittest.mock import AsyncMock
+
+import fastapi
+import pytest
+from starlette.requests import Request
+
+from taskiq_dashboard.api.routers.task import TaskFilter, argument_key_options, router, search_tasks
+from taskiq_dashboard.domain.dto.task import Task
+from taskiq_dashboard.domain.dto.task_status import TaskStatus
+
+
+def _make_request(path: str = '/') -> Request:
+    app = fastapi.FastAPI()
+    app.include_router(router)
+    scope = {
+        'type': 'http',
+        'method': 'GET',
+        'path': path,
+        'headers': [],
+        'query_string': b'',
+        'app': app,
+    }
+    return Request(scope)
+
+
+@pytest.mark.asyncio
+async def test_when_htmx_list_request_then_skip_metadata_queries_and_normalize_arg_filters() -> None:
+    repository = AsyncMock()
+    repository.find_tasks.return_value = [
+        Task(
+            id=uuid.uuid4(),
+            name='sample_task',
+            status=TaskStatus.COMPLETED,
+            worker='worker',
+        )
+    ]
+
+    response = await search_tasks(
+        request=_make_request('/'),
+        repository=repository,
+        query=TaskFilter(task_name=' sample_task ', arg_key=' entity_id ', arg_value='   '),
+        hx_request=True,
+    )
+
+    repository.find_tasks.assert_awaited_once_with(
+        name='',
+        task_name='sample_task',
+        arg_key='',
+        arg_value='',
+        status=None,
+        limit=30,
+        offset=0,
+        sort_by='started_at',
+        sort_order='desc',
+    )
+    repository.find_task_names.assert_not_awaited()
+    repository.find_argument_keys.assert_not_awaited()
+    expected_url = (
+        '/?q=&task_name=sample_task&arg_key=&arg_value=&status=null'
+        '&sort_by=started_at&sort_order=desc'
+    )
+    assert response.headers['HX-Push-Url'] == expected_url
+
+
+@pytest.mark.asyncio
+async def test_when_fetching_arg_keys_and_selected_key_not_available_then_clear_selection() -> None:
+    repository = AsyncMock()
+    repository.find_argument_keys.return_value = ['entity_id', 'operation']
+
+    response = await argument_key_options(
+        request=_make_request('/filters/arg-keys'),
+        repository=repository,
+        task_name='sample_task',
+        arg_key='missing_key',
+    )
+
+    repository.find_argument_keys.assert_awaited_once_with(task_name='sample_task')
+    assert response.context['keys'] == ['entity_id', 'operation']
+    assert response.context['selected_arg_key'] == ''
+
+
+@pytest.mark.asyncio
+async def test_when_htmx_request_has_arg_filters_without_task_name_then_ignore_arg_filters() -> None:
+    repository = AsyncMock()
+    repository.find_tasks.return_value = []
+
+    await search_tasks(
+        request=_make_request('/'),
+        repository=repository,
+        query=TaskFilter(task_name='  ', arg_key='entity_id', arg_value='A-100'),
+        hx_request=True,
+    )
+
+    repository.find_tasks.assert_awaited_once_with(
+        name='',
+        task_name='',
+        arg_key='',
+        arg_value='',
+        status=None,
+        limit=30,
+        offset=0,
+        sort_by='started_at',
+        sort_order='desc',
+    )
diff --git a/tests/unit/test_task_service_sqlite.py b/tests/unit/test_task_service_sqlite.py
new file mode 100644
index 0000000..ea0c838
--- /dev/null
+++ b/tests/unit/test_task_service_sqlite.py
@@ -0,0 +1,152 @@
+import uuid
+
+import pytest
+import sqlalchemy as sa
+
+from taskiq_dashboard.infrastructure.database.schemas import SqliteTask, sa_metadata
+from taskiq_dashboard.infrastructure.database.session_provider import AsyncPostgresSessionProvider
+from taskiq_dashboard.infrastructure.repositories import TaskRepository
+from taskiq_dashboard.infrastructure.settings import SqliteSettings
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_when_filtering_sqlite_tasks_by_argument_key_value_then_match_kwargs_only(tmp_path) -> None:
+    sqlite_file = tmp_path / 'taskiq_dashboard_test.db'
+    session_provider = AsyncPostgresSessionProvider(
+        connection_settings=SqliteSettings(file_path=str(sqlite_file)),
+    )
+    async with session_provider.session() as session:
+        connection = await session.connection()
+        await connection.run_sync(sa_metadata.create_all, tables=[SqliteTask.__table__])
+    repository = TaskRepository(session_provider=session_provider, task_model=SqliteTask)
+
+    try:
+        async with session_provider.session() as session:
+            await session.execute(
+                sa.insert(SqliteTask),
+                [
+                    {
+                        'id': uuid.uuid4(),
+                        'name': 'task_one',
+                        'status': 1,
+                        'worker': 'worker-1',
+                        'args': ['approve', 'C6380048', 'u_legacy'],
+                        'kwargs': {'entity_id': 'A-100', 'operation': 'create'},
+                        'labels': {},
+                    },
+                    {
+                        'id': uuid.uuid4(),
+                        'name': 'task_one',
+                        'status': 1,
+                        'worker': 'worker-1',
+                        'args': [],
+                        'kwargs': {'entity_id': 'A-200', 'operation': 'update'},
+                        'labels': {},
+                    },
+                ],
+            )
+
+        filtered = await repository.find_tasks(
+            task_name='task_one',
+            arg_key='entity_id',
+            arg_value='A-100',
+        )
+
+        assert len(filtered) == 1
+        assert filtered[0].kwargs['entity_id'] == 'A-100'
+    finally:
+        await session_provider.close()
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_when_requesting_sqlite_argument_keys_then_return_only_task_specific_kwargs_keys(tmp_path) -> None:
+    sqlite_file = tmp_path / 'taskiq_dashboard_test.db'
+    session_provider = AsyncPostgresSessionProvider(
+        connection_settings=SqliteSettings(file_path=str(sqlite_file)),
+    )
+    async with session_provider.session() as session:
+        connection = await session.connection()
+        await connection.run_sync(sa_metadata.create_all, tables=[SqliteTask.__table__])
+    repository = TaskRepository(session_provider=session_provider, task_model=SqliteTask)
+
+    try:
+        async with session_provider.session() as session:
+            await session.execute(
+                sa.insert(SqliteTask),
+                [
+                    {
+                        'id': uuid.uuid4(),
+                        'name': 'task_one',
+                        'status': 1,
+                        'worker': 'worker-1',
+                        'args': [],
+                        'kwargs': {'entity_id': 'A-100', 'operation': 'create'},
+                        'labels': {},
+                    },
+                    {
+                        'id': uuid.uuid4(),
+                        'name': 'task_two',
+                        'status': 1,
+                        'worker': 'worker-2',
+                        'args': [],
+                        'kwargs': {'external_id': 'EXT-1001'},
+                        'labels': {},
+                    },
+                ],
+            )
+
+        keys = await repository.find_argument_keys(task_name='task_one')
+        assert keys == ['entity_id', 'operation']
+    finally:
+        await session_provider.close()
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_when_filtering_sqlite_without_task_name_then_ignore_arg_key_value_filter(tmp_path) -> None:
+    sqlite_file = tmp_path / 'taskiq_dashboard_test.db'
+    session_provider = AsyncPostgresSessionProvider(
+        connection_settings=SqliteSettings(file_path=str(sqlite_file)),
+    )
+    async with session_provider.session() as session:
+        connection = await session.connection()
+        await connection.run_sync(sa_metadata.create_all, tables=[SqliteTask.__table__])
+    repository = TaskRepository(session_provider=session_provider, task_model=SqliteTask)
+
+    try:
+        async with session_provider.session() as session:
+            await session.execute(
+                sa.insert(SqliteTask),
+                [
+                    {
+                        'id': uuid.uuid4(),
+                        'name': 'task_one',
+                        'status': 1,
+                        'worker': 'worker-1',
+                        'args': [],
+                        'kwargs': {'entity_id': 'A-100'},
+                        'labels': {},
+                    },
+                    {
+                        'id': uuid.uuid4(),
+                        'name': 'task_two',
+                        'status': 1,
+                        'worker': 'worker-2',
+                        'args': [],
+                        'kwargs': {'entity_id': 'A-200'},
+                        'labels': {},
+                    },
+                ],
+            )
+
+        filtered = await repository.find_tasks(
+            task_name='',
+            arg_key='entity_id',
+            arg_value='A-100',
+        )
+
+        assert len(filtered) == 2
+    finally:
+        await session_provider.close()