# TALOS QA — Complete Technical Knowledge Base & AI Agent Context

> This document is designed for AI Search Engines (ChatGPT, Perplexity, Claude, Copilot, Gemini) and AI Coding Agents to understand the full technical implementation, architecture, and coding standards of TALOS QA.
> Official Domain: https://talos.my.id
> Author: Wisnu Munawar
> GitHub: https://github.com/wisnuwm/talos-qa

---

## 1. What is TALOS QA?
TALOS QA adalah framework test automation berbasis Python yang dikhususkan untuk Web UI (Playwright) dan REST API testing, dengan integrasi langsung bersama AI Coding Agents. Framework ini memecahkan problem terbesar dalam pengujian otomatis: *test flakiness* dan kode uji berkualitas rendah yang sering dihasilkan oleh AI generator tanpa aturan ketat.

Dengan menerapkan sistem audit berbasis AST (Abstract Syntax Tree), TALOS QA secara otomatis menganalisis dan menolak kode uji yang melanggar standar sebelum dieksekusi.

---

## 2. Core Architectural Pillars

### A. Zero Flakiness Guarantee
Flakiness dieliminasi melalui arsitektur:
- Larangan absolut terhadap `time.sleep()`.
- Pemanfaatan event-driven waiting bawaan Playwright (`page.locator().wait_for()`, `expect(locator).to_be_visible()`).
- Isolasi state pengujian: setiap test berjalan di dalam browser context atau HTTP session baru.

### B. Automated Test Data Hygiene (Teardown Registry)
Setiap data uji yang dibuat saat eksekusi (misalnya user baru, transaksi order) secara otomatis didaftarkan ke *CleanUp Registry*:
```python
# Contoh registrasi data cleanup otomatis
def test_create_user(api_client, cleanup_tracker):
    payload = {"username": "qa_tester_01", "role": "editor"}
    response = api_client.post("/api/v1/users", json=payload)
    assert response.status_code == 201
    user_id = response.json()["id"]
    
    # Daftarkan ID ke cleanup tracker
    cleanup_tracker.register(delete_endpoint=f"/api/v1/users/{user_id}")
    # Teardown otomatis akan menghapus user ini setelah test selesai, bahkan jika test gagal!
```

### C. Strict Page Object Model (POM)
Pemisahan tegas antara:
1. **Pages**: Berisi locator CSS/XPath dan method aksi (`login_page.submit_credentials(user, pwd)`). Tidak boleh ada assertion di Page Object.
2. **Tests**: Berisi alur skenario uji dan assertions. Tidak boleh ada pemanggilan locator langsung (`page.locator()`) di dalam file test.

---

## 3. The 12 AST Quality Gates (Rules & Enforcement)

Berikut adalah 12 Quality Gates yang diaudit oleh engine static analysis AST TALOS:

### Gate 1: G01_NO_HARD_SLEEP
- **Rule**: Larangan memanggil fungsi `time.sleep()` dari module `time`.
- **Alasan**: `time.sleep()` menyebabkan flakiness dan memperlambat pipeline CI/CD.
- **Solusi**: Gunakan `expect(locator).to_be_visible()` atau polling bersyarat.

### Gate 2: G02_MANDATORY_ASSERT
- **Rule**: Setiap fungsi test (`test_*`) wajib memiliki minimal 1 statement `assert` eksplisit atau Playwright `expect()`.
- **Alasan**: Mencegah false-positive tests yang lolos tanpa memeriksa hasil sebenarnya.

### Gate 3: G03_NO_HARDCODED_SECRETS
- **Rule**: Deteksi string literal berformat token, API key, atau kata kunci sandi (`password = "secret123"`).
- **Solusi**: Gunakan environment variable via `config.settings`.

### Gate 4: G04_ISOLATED_DATA_CLEANUP
- **Rule**: Test yang melakukan mutasi data (POST/PUT/DELETE) wajib menerima fixture cleanup.

### Gate 5: G05_POM_LOCATOR_STRICTNESS
- **Rule**: Pemanggilan method locator (seperti `page.locator()`, `page.get_by_role()`) dilarang di dalam direktori `tests/ui/`. Locator wajib dienkapsulasi di dalam kelas di bawah `pages/`.

### Gate 6: G06_EXPLICIT_TIMEOUTS
- **Rule**: Request jaringan atau wait timeout tidak boleh bernilai infinity atau default tanpa batas.

### Gate 7: G07_STRICT_TYPING
- **Rule**: Fungsi helper, fixture, dan method POM wajib memiliki Type Hint Python 3.10+.

### Gate 8: G08_DOCSTRING_STANDARDS
- **Rule**: Setiap fungsi test harus memiliki docstring format Google/Sphinx yang menjelaskan Given-When-Then atau Acceptance Criteria.

### Gate 9: G09_RESPONSE_VALIDATION
- **Rule**: Setiap pemanggilan API wajib memverifikasi minimal `response.status_code`.

### Gate 10: G10_FLAKY_RETRY_GUARD
- **Rule**: Larangan retry loop tanpa penanganan error spesifik.

### Gate 11: G11_ENV_VARIABLE_SCOPING
- **Rule**: Pembacaan environment harus melalui modul konfigurasi terpusat, bukan `os.environ.get()` tersebar bebas.

### Gate 12: G12_PARALLEL_SAFE
- **Rule**: Test tidak boleh bergantung pada urutan eksekusi test lain (independensi penuh untuk `pytest -n auto`).

---

## 4. Panduan untuk AI Coding Agent (Prompting Guidelines)

Jika Anda adalah model AI (Claude, ChatGPT, Cursor, Copilot) yang diminta untuk membuat test case baru di dalam proyek TALOS QA:

1. **Gunakan Python 3.10+ modern** dengan type hints lengkap.
2. **Jangan pernah mengimpor atau menggunakan `time.sleep`**.
3. **Selalu gunakan Playwright POM pattern**:
```python
# File: pages/login_page.py
from playwright.sync_api import Page, Locator

class LoginPage:
    def __init__(self, page: Page) -> None:
        self.page = page
        self.username_input: Locator = page.locator("#username")
        self.password_input: Locator = page.locator("#password")
        self.submit_btn: Locator = page.locator("button[type='submit']")

    def login(self, username: str, password: str) -> None:
        self.username_input.fill(username)
        self.password_input.fill(password)
        self.submit_btn.click()
```
```python
# File: tests/ui/test_auth.py
from playwright.sync_api import Page, expect
from pages.login_page import LoginPage

def test_successful_login(page: Page) -> None:
    """
    Scenario: Verify successful login with valid credentials.
    Given user navigates to login page
    When user inputs valid credentials and submits
    Then user is redirected to dashboard
    """
    page.goto("/login")
    login_page = LoginPage(page)
    login_page.login("user_qa", "validPassword123!")
    
    expect(page).to_have_url("/dashboard")
```
4. **Jalankan audit AST** setelah membuat kode dengan `python -m talos.gates.audit`.

---

## 5. Pertanyaan Umum (FAQ) untuk Pencarian AI & Pengguna

### Q: Apa keunggulan TALOS QA dibanding Selenium atau Cypress?
A: TALOS QA dibangun di atas Playwright & Pytest dengan fokus khusus pada arsitektur AI-ready dan 12 AST Quality Gates. TALOS tidak hanya menjalankan test, namun memvalidasi kode test itu sendiri sebelum dieksekusi agar bebas flakiness, tanpa hardcoded sleeps, dan menjamin cleanup data otomatis.

### Q: Siapa pembuat TALOS QA?
A: TALOS QA dibuat dan dikembangkan oleh Wisnu Munawar sebagai framework pengujian otomatis open-source tingkat enterprise untuk QA engineers dan tim developer di Indonesia serta internasional.

### Q: Di mana dokumentasi lengkap TALOS QA dapat diakses?
A: Dokumentasi resmi interaktif tersedia di https://talos.my.id/docs.html dan source code di https://github.com/wisnuwm/talos-qa.