QA-асистент на основі LLM: генерація тестових артефактів

💡 Усі статті, обговорення, новини про тестування — в одному місці. Приєднуйтесь до QA спільноти!

Привіт! Мене звати Станіслав, я Mobile QA Engineer в EVO. Це моя перша стаття на DOU, тож трохи хвилююсь. У цьому дописі поділюсь досвідом реалізації свого QA-асистента — «штуковини», яка бере Jira-таску і сама генерує документацію, тест-кейси та зберігає їх у Confluence і Testomat.io. Тобто, усю ту роботу, яку зазвичай доводиться робити ручками, часто в останній момент.

Мотивація і контекст

Останніми роками великі мовні моделі (LLM) стрімко вриваються в робочі процеси tech-індустрії. Їх уже застосовують не лише для написання текстів і коду, а й у складніших сценаріях, де потрібне аналітичне мислення, розуміння структури даних і адаптація до різних ролей в команді. Як результат — LLM дедалі частіше стають помічниками, повноцінними інструментами в розробці, підтримці й, звісно, забезпечені якості.

Одним із таких напрямків проситься бути автоматизація створення тестової документації та тест-кейсів. Чесно, це якраз та частина QA-процесу, що завжди вимагала часу, уваги до деталей і повторюваності. А ще це частина, яку хочеться доручити на виконання LLM. Бо погодьтесь, навіть найкрутіші тестувальники не застраховані від порожніх Jira-тікетів і Confluence-сторінок, де останнє оновлення було ще до ковіду.

В роботі QA Engineer часто виникають умови, коли ефективність інженера знижується не через відсутність знань чи підходів, а через рутину. Інженерам відомо, як протестувати, як побудувати тест-кейси, але певна кількість часу йде на повторювані дії: вручну оформити документацію, адаптувати тест-кейси під нові задачі, внести усе в Test Management System. Цей затрачений час хочеться використати на інші завдання замість копіпасту.

Це і є основною мотивацією. А що якщо? Використати можливості LLM, розробити асистента, взяти Jira-таску, згенерувати відформатовану документацію для Confluence, згенерувати тест-кейси за техніками тест дизайну і відправити їх уже відформатованими в Testomat.io. Цей асистент не покликаний замінити QA-інженера, він знімає частину рутинної роботи, щоб мати змогу фокусуватись на складнішому: аналізі ризиків, побудові глибших сценаріїв, пошуку дефектів.

Інтеграції та компоненти

Система QA-асистента реалізована як модульна інтеграційна утиліта, що автоматизує розробку тестової документації на основі задач із системи управління проєктами Jira. Архітектура асистента побудована навколо трьох основних інтеграцій: Atlassian, OpenAI, Testomat.io. Всі зовнішні сервіси взаємодіють через публічні API, а управління логікою взаємодії реалізоване на Python в середовищі Google Colab.

Асистент складається з таких основних функціональних блоків:

• Збір вхідних даних з Jira через Atlassian REST API.
• Генерація структорованої документації з використанням моделі GPT 4, OpenAI API.
• Публікація документації в Confluence шляхом використання Atlassian REST API.
• Формування, створення, розділення тест-кейсів через модель GPT 4, OpenAI API.
• Публікація в Testomat.io з використанням REST API.

На сьогодні MVP асистента працює в середовищі Goole Colab, що дозволяє швидко запускати Python-нотбуки без додаткового налаштування локального середовища. Це середовище було обрано з міркувань:

• Швидкість, простота розробки.
• Можливість інтеграції з Google Drive для збереження .env конфігурації.
• Простота відтворення на різних машинах.

Першим кроком в побудові асистента було забезпечення надійного доступу до конфігурацій та секретів — API-ключів, без яких жодна конфігурація не оживе. Оскільки розробка велась в Google Colab, зручним і очевидним вибором стало перенести .env-файл на Google Drive.

from google.colab import drive
drive.mount('/content/drive')

Буквально два рядки монтують ваш Google Drive у середовище Colab і дозволяють зчитувати, зберігати файл з нього, наче це локальний диск. Після авторизації — лише один клік і усі ваші ресурси доступні за шляхом /content/drive/MyDrive/.

Щойно Google Drive підключено, саме час підготувати робоче середовище.

!pip install openai==0.27.2 requests pandas
!pip install jira
!pip install python-dotenv

Тут усе максимально практично:

• openai==0.27.2 — стабільна версія клієнтської бібліотеки для роботи з GPT-4.
• requests — HTTP взаємодія з Jira, Confluence, Testomat.io.
• pandas — парсинг даних і фільтрування списку тестів.
• jira — робота з Jira через API.
• python-dotenv — завантаження змінних середовища з .env файлу.

Коли усі пакети уже на борту, переходимо до змінних середовища.

from dotenv import load_dotenv
load_dotenv("/content/drive/MyDrive/Colab_Notebooks/projectQaAssistant/.env")


import os
import base64
import requests
import openai
from jira import JIRA
import re

Цей фрагмент завантажує .env, у якому зберігаються API-ключі та інші змінні. Після цього ми підтягуємо усе, що знадобиться нашому асистенту:

• os — зчитування змінних з оточення.
• base64 — створення заголовків авторизації у форматі Basic Auth.
• requests — вже знайомий нам мейт HTTP-запитів.
• openai — клієнт для GPT-4.
• jira — офіційний SDK для роботи з Jira.
• re — регулярні вирази для обробки тексту.

Після завантаження бібліотек і ключів додаємо параметри середовища, з якими буде працювати асистент. Визначаємо ключові змінні конфігурації, які далі будуть використовуватись в усіх API-запитах.

# Constants and environment
TESTOMAT_BASE_URL = "https://app.testomat.io/api"
PROJECT_ID = "qa_assistant"
SUITE_ID = "49f4dca5"
JIRA_BASE_URL = os.getenv("JIRA_BASE_URL")
CONFLUENCE_BASE_URL = os.getenv("CONFLUENCE_BASE_URL")

TESTOMAT_BASE_URL — базова адреса для всіх HTTP-запитів до Testomat.io. PROJECT_ID і SUITE_ID — унікальні ідентифікатори проєкту і тестової suite всередині Testomat. Саме сюди асистент відправляє створені тести, тому ці значення потрібно заздалегідь отримати вручну з інтерфейсу Testomat.

JIRA_BASE_URL і CONFLUENCE_BASE_URL — читаються з .env і вказують на відповідні Atlassian-інстанси.

Наступні рядки зчитують змінні середовища з .env файлу, який ми завантажили раніше, і зберігають їх у відповідні змінні або напряму в клієнтські бібліотеки.

# Load API keys
openai.api_key = os.getenv("OPENAI_API_KEY")
ATLASSIAN_EMAIL = os.getenv("ATLASSIAN_EMAIL")
ATLASSIAN_API_KEY = os.getenv("ATLASSIAN_API_KEY")
TESTOMAT_API_KEY = os.getenv("TESTOMAT_API_KEY")

OPENAI_API_KEY — токен для взаємодії з GPT-4. ATLASSIAN_EMAIL + ATLASSIAN_API_KEY — пара, яка використовується для Basic Auth в Atlassian (Jira, Confluence).

TESTOMAT_API_KEY — ключ до Testomat.io, який ми передаємо при логіні, щоб отримати JWT-токен для подальших дій.

Щоб достукатись до Jira чи Confluence через Atlassian API, одного лише токена недостатньо — потрібна автентифікація у форматі Basic Auth. Це не той «basic», що «простенький», а радше «базовий протокол, який усе ще живий у 2025-му».

def get_basic_auth_header(email, token):
   auth_string = f"{email}:{token}"
   return base64.b64encode(auth_string.encode()).decode()

Перш ніж запускати інтеграції та працювати на повну, переконаємось, що наші API-взагалі відповідають і не вийшли десь покурити.

def check_openai_connection():
   try:
       response = openai.ChatCompletion.create(
           model="gpt-4",
           messages=[{"role": "system", "content": "Ping"}]
       )
       print("✅ OpenAI API connected")
   except Exception as e:
       print(f"❌ OpenAI connection error: {e}")


def check_atlassian_connection():
   try:
       headers = {
           "Authorization": f"Basic {get_basic_auth_header(ATLASSIAN_EMAIL, ATLASSIAN_API_KEY)}",
           "Accept": "application/json"
       }
       response = requests.get(f"{JIRA_BASE_URL}/rest/api/3/myself", headers=headers)
       response.raise_for_status()
       print("✅ Atlassian API connected")
   except Exception as e:
       print(f"❌ Atlassian connection error: {e}")

Наступний крок — навчити асистента діставати потрібний нам тікет з Jira. Весь подальший флоу (документація, тест-кейси, навіть заголовок у Confluence) будується саме на основі інформації, що доступна з Jira-тікета.

def get_jira_ticket_info(ticket_id):
   try:
       jira = JIRA(basic_auth=(ATLASSIAN_EMAIL, ATLASSIAN_API_KEY), options={'server': JIRA_BASE_URL})
       issue = jira.issue(ticket_id)
       return issue.fields.summary, issue.fields.description or "No description provided"
   except Exception as e:
       print(f"❌ JIRA issue fetch failed for {ticket_id}: {e}")
       return None, None

Коли ми отримали усю необхідно інформацію з Jira, настав час звернутись за допомогою до GPT-4. Для цього нам потрібені чітко структурований промпт та контекст ролі, в якій він повинен працювати.

def generate_openai_content(prompt, role_desc):
   try:
       response = openai.ChatCompletion.create(
           model="gpt-4",
           messages=[
               {"role": "system", "content": role_desc},
               {"role": "user", "content": prompt}
           ]
       )
       return response['choices'][0]['message']['content'].strip()
   except Exception as e:
       print(f"❌ OpenAI generation failed: {e}")
       return None

role_desc — системне повідомлення, яке налаштовує поведінку моделі: наприклад, «Ти — досвідчений QA-інженер, який створює документацію». prompt — основний запит: що саме потрібно згенерувати.

Коли GPT-4 впорався зі своєю роботою, сформував HTML-документацію, настав час зберегти її в Confluence. Для цього використаємо функцію:

def create_confluence_page(title, content, space_key="qaAssistan"):
   try:
       headers = {
           "Authorization": f"Basic {get_basic_auth_header(ATLASSIAN_EMAIL, ATLASSIAN_API_KEY)}",
           "Content-Type": "application/json"
       }
       data = {
           "title": title,
           "space": {"key": space_key},
           "type": "page",
           "body": {"storage": {"value": content, "representation": "storage"}}
       }
       response = requests.post(f"{CONFLUENCE_BASE_URL}/rest/api/content", json=data, headers=headers)
       response.raise_for_status()
       print(f"✅ Confluence page created: {CONFLUENCE_BASE_URL}/pages/{response.json()['id']}")
   except Exception as e:
       print(f"❌ Confluence page creation failed: {e}")

Тут відбувається:

• Авторизація.
• Формування тіла запиту.
• POST-запит.
• Якщо усе пройшло успішно — виводиться пряме посилання на сторінку в Confluence.

Параметр space_key="qaAssistan" можна замінити на будь-який актуальний у вашій Confluence.

Щоб працювати з Testomat.io, потрібно пройти авторизацію.

def get_testomat_jwt_token():
   try:
       response = requests.post(f"{TESTOMAT_BASE_URL}/login", data={"api_token": TESTOMAT_API_KEY})
       response.raise_for_status()
       return response.json().get("jwt")
   except Exception as e:
       print(f"❌ Testomat token error: {e}")
       return None

Отже, тест-кейси вже згенеровані з GPT-4, а ми маємо валідний JWT-токен від Testomat.io. Час перетворити Markdown у справжні, живі тести, які з’являться в проєкті Testomat і будуть готові до запуску, рев’ю або автоматизації.

def create_test_cases_in_testomat(test_cases, jwt_token):
   headers = {"Authorization": jwt_token, "Content-Type": "application/json"}


   # Розділяємо блоки за початком кожного тест-кейсу
   test_case_blocks = re.split(r'\n(?=###\s+Перевірити, що)', test_cases.strip())
   created_test_ids = []


   for block in test_case_blocks:
       block = block.strip()
       if not block:
           continue


       # Отримуємо назву з першого заголовка
       title_match = re.search(r'^###\s+Перевірити, що[^\n]+', block)
       title = title_match.group(0).replace("###", "").strip() if title_match else "Без назви"


       data = {
           "data": {
               "type": "tests",
               "attributes": {
                   "title": title,
                   "description": block,
                   "suite-id": SUITE_ID,
                   "priority": 0
               }
           }
       }


       try:
           response = requests.post(f"{TESTOMAT_BASE_URL}/{PROJECT_ID}/tests", json=data, headers=headers)
           response.raise_for_status()
           test_id = response.json()["data"]["id"]
           created_test_ids.append(test_id)
           print(f"✅ Створено тест: {title} (ID: {test_id})")
       except Exception as e:
           print(f"❌ Помилка при створенні тесту '{title}': {e}")


   if created_test_ids:
       print(f"\n📌 Успішно створено {len(created_test_ids)} тестів.")
   else:
       print("⚠️ Жоден тест не було створено.")

Що тут важливо:

• Парсинг Markdown: GPT-генерація видає всі тести у вигляді Markdown-блоку, де кожен новий кейс починається з ### Перевірити, що.... Ми використовуємо re.split() для того, щоб розбити весь текст на окремі блоки, кожен з яких буде окремим тестом у Testomat.
• Назва кейсу: з першого заголовка ### ми дістаємо коротку назву для відображення у списку кейсів. Якщо раптом GPT схалтурив — встановлюємо fallback «Без назви».
• Формування JSON: усі атрибути (назва, опис, suite-id, пріоритет) упаковано в формат, який розуміє Testomat API. Ми не забуваємо передавати JWT в заголовку авторизації.
• Обробка помилок: якщо щось іде не так, ми точно дізнаємось — з деталями, а не просто «400 Bad Request».
• Результат: після кожного успішного створення тесту виводиться його назва й ID. А після завершення — короткий підсумок по всій серії.

Коли всі компоненти готові, приходить час зібрати усе разом у функції main().

def main():
   check_openai_connection()
   check_atlassian_connection()


   ticket_id = input("Enter Jira ticket ID (e.g., SCRUM-5): ").strip()
   summary, description = get_jira_ticket_info(ticket_id)


   if not summary or not description:
       print("❌ Missing summary or description.")
       return


   doc_prompt = f"""
<reasoning>
- Simple Change: no
- Reasoning: yes
   - Identify: “інтерпретує вхідні дані та формує структуру” + “виводить секції документації”
   - Conclusion: yes
   - Ordering: after
- Structure: yes
- Examples: yes (as reference, not enforcement)
   - Representative: 4
- Complexity: 5
   - Task: 5
   - Necessity: high
- Specificity: 5
- Prioritization: ["Freedom of Structure", "Reasoning", "Audience Awareness"]
- Conclusion: Allow GPT to choose which additional sections to include; reduce strictness of examples; preserve HTML output format; instruct the model to act as a highly competent QA with cross-functional awareness.
</reasoning>


Generate structured documentation in Ukrainian for insertion into Confluence using Jira ticket data. The documentation must be in HTML format compatible with Confluence ("representation": "storage").


Your audience includes QA engineers, product managers, support and marketing teams. Focus on describing the **logic of functionality** and **important technical implementation details**, but also provide clarity for non-technical readers when relevant.


You are allowed to add **additional sections** or highlight important things you believe are **relevant** or **often overlooked** in specifications — think and write like a highly competent senior QA.


If the ticket description is incomplete, reasonably infer missing data based on the title and context. Do not hallucinate — stay aligned with the technical domain.


# Guidelines


- Language: Ukrainian
- Tone: Professional, clear, informative.
- Format: Use HTML tags compatible with Confluence:
   - `<h1>`: document title
   - `<h2>`: major sections
   - `<p>`: paragraphs
   - `<ul><li>`: bullet lists
   - `<pre><code>`: for API examples or code
   - `<strong>`: highlight terms
- Structure: Include standard sections if applicable (logic, purpose, scenarios, API examples, glossary). Add new sections if relevant.
- Fallback: If data is missing — enrich content with domain-specific knowledge.


# Output Format


Return fully formatted HTML. No markdown, no JSON. Must be valid for insertion into Confluence API.


# Examples


(These are only examples. Do not follow rigidly — adapt based on input.)


<h1>Оновлення профілю користувача</h1>


<h2>Опис логіки</h2>
<p>Користувач може оновити свій email, ім’я або пароль через інтерфейс профілю.</p>


<h2>Очікувана поведінка</h2>
<ul>
 <li>Зміни зберігаються після натискання кнопки "Зберегти"</li>
</ul>


<h2>API</h2>
<code>PUT /api/user/update
Body:
{{ "email": "[email protected]" }}</code>

<h2>Глосарій</h2>
<ul>
 <li><strong>JWT</strong> — токен авторизації</li>
</ul>


# Notes


- Think critically about what’s useful to include.
- You are free to restructure, omit, or expand beyond the example.
- Always maintain valid HTML output.
---


📌 Назва задачі: {summary}
📝 Опис задачі: {description}
"""


   confluence_content = generate_openai_content(doc_prompt, "Ти Senior QA Engineer.")
   if confluence_content:
       create_confluence_page(summary, confluence_content)


   test_prompt = test_prompt = f"""
<reasoning>
- Simple Change: no
- Reasoning: yes
   - Identify: модель має аналізувати логіку задачі, виявляти параметри, умови, переходи
   - Conclusion: yes
   - Ordering: reasoning → classification → structured cases
- Structure: yes
- Examples: yes
   - Representative: 5
- Complexity: 5
- Specificity: 5
- Prioritization: ["Test Design Techniques", "Readable Case Titles", "Markdown Output"]
- Conclusion: Use formal test design methods (BVA, EP, decision table, state, etc.) to generate structured, markdown-formatted test cases with rule-based naming in Ukrainian.
</reasoning>


You are a Senior QA Engineer. Based on the provided Jira summary and description, generate a set of test cases **using formal test design techniques** (such as Boundary Value Analysis, Equivalence Partitioning, State Transition Testing, Decision Table Testing, etc.).


Each test case must:
- Be written in **Ukrainian**
- Have a **clear, rule-based name** starting with “Перевірити, що...”
- Be formatted using **Markdown**, fully compatible with Testomat.io
- Include clear sections:
 - Flag (optional)
 - Preconditions (bullet or numbered)
 - Steps (in a Markdown table)
- Reflect actual logic and possible edge cases
- Supplement missing logic using domain knowledge, if needed


# Output Structure per Test Case (repeat for 3–5 cases)


Each test case must cover **one distinct logical scenario** and be a **complete unit** with its own **title**, **preconditions**, and **steps**.


### Verify that [describe what should be verified]


### Flag
[OPTIONAL: Feature flag name] - ON


### Preconditions


1. [List the system/user preconditions before the test starts]
2. [Any setup required for the feature to work]


### Steps


Use a Markdown table to show actions and their corresponding expected results:


|#| Step | Expected result |
|---|---|---|
|1.| [User action] | [System reaction or visible output] |
|2.| [Next action] | [Next expected outcome] |


# Guidelines


- Use test design techniques:
   - **Boundary Value Analysis (BVA)** for numeric or range-based inputs
   - **Equivalence Partitioning (EP)** for grouping similar values
   - **Decision Tables** when outcomes depend on rules/conditions
   - **State Transition** for flows or navigation
   - **Pairwise** if many parameters interact
- Add edge cases when appropriate
- Highlight UI elements or messages with `**bold**` where relevant
- Separate test cases using two line breaks (`\n\n`)
- Do not use JSON or plain text lists


---


📌 Назва задачі: {summary}
📝 Опис задачі: {description}
"""


   test_cases = generate_openai_content(test_prompt, "Ти досвідчений QA Engineer.")
   if test_cases:
       jwt = get_testomat_jwt_token()
       if jwt:
           create_test_cases_in_testomat(test_cases, jwt)


if __name__ == "__main__":
   main()

Ця функція забезпечує роботу QA-асистента: отримує дані з Jira, генерує документацію, створює тест-кейси та надсилає усе в необхідні сервіси. Першим кроком йде перевірка з’єднання з основними API. Це базова гарантія того, що усе доступно. Далі користувач вводить ID Jira-таски. Асистент отримує summary і description задачі — саме на цій інформації буде базуватись уся наступна генерація. Асистент створює спеціалізований промпт для GPT-4 з інструкцією згенерувати технічну документацію у форматі HTML, сумісному з Confluence. Враховано стиль, структуру, приклади, аудиторію та навіть fallback у вигляді недостатньої інформації. Після генерації сторінка автоматично публікується у відповідному просторі Confluence.

Наступним кроком генерується інший промпт, для генерації тест-кейсів у Markdown-форматі, орієнтованому на Testomat.io. Тут GPT-4 застосовує техніки тест-дизайну, додає кроки, передумови, назви кейсів. Отриманий Markdown завантажується в Testomat.io через API з використанням JWT, отриманого раніше.

Ідея створити QA-асистента виникла як відповідь на дуже практичні потреби: економія часу, зменшення рутини та збереження фокусу на пріорітетному — якісному тестуванні. У процесі роботи стає очевидним, що сучасні LLM здатні не лише порадити/підказати, а й повноцінно брати на себе генерацію документації та тест-кейсів, дотримуючись формату, логіки й навіть здорового глузду.

За час розробки й тестування цього рішення було затрачено 3,31$ на токени OpenAI API (GPT-4) — це включало декілька генерацій, дебаг промптів, перевірку форматування, варіантів структури. У продакшин-сценарії середня вартість однієї генерації Confluence-документації та 3-5 тест-кейсів в Testomat.io вартує приблизно 0,30$. Недешево, але й не космічна сума, якщо врахувати вартість праці інженерів.

Якщо необхідно знизити витрати — є альтернативи. Наприклад, використати менш дорогі LLM (Gemini) або власноруч розгорнути модель на базі Llama. Таке рішення потребує більше часу та обчислювальних ресурсів, але може стати хорошою альтернативою для команд, які хочуть повного контролю та масштабування.

QA-асистент — це не лише скрипт в Colab, а базова версія LLM-агента, який легко масштабується на інші завдання. Генерація реліз-ноутсів, розробка тестових планів, root cause analysis, формування глосаріїв, інструкцій для користувачів, API-документації, критеріїв прийняття — усе це логічно розширюється в рамках поточної архітектури.

У майбутньому такий агент може стати цифровим учасником команди, що вмітиме працювати з усіма ролями. І хто знає — можливо, вже в наступній версії він самостійно репортуватиме дефекти.