Metadata-Version: 2.5
Name: fsq-agent
Version: 0.3.1
Summary: Goal-driven FSQ automated testing agent with a local agent engine, OpenAI-compatible model access, harness actions, local utilities, observation, and reporting.
Project-URL: Documentation, https://github.com/FSQ-lab/FSQ#readme
Project-URL: Issues, https://github.com/FSQ-lab/FSQ/issues
Project-URL: Repository, https://github.com/FSQ-lab/FSQ
Author: Microsoft Corporation
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: aiofiles==25.1.0
Requires-Dist: appium-python-client==5.3.1
Requires-Dist: click==8.3.3
Requires-Dist: google-genai==2.21.0
Requires-Dist: httpx==0.28.1
Requires-Dist: jinja2==3.1.6
Requires-Dist: openai==2.34.0
Requires-Dist: pillow==12.3.0
Requires-Dist: playwright==1.60.0
Requires-Dist: pydantic-settings==2.14.2
Requires-Dist: pydantic==2.13.3
Requires-Dist: pywinauto==0.6.9
Requires-Dist: pyyaml==6.0.3
Requires-Dist: ruamel-yaml==0.18.16
Requires-Dist: structlog==25.5.0
Requires-Dist: uiautomator2==3.5.2
Provides-Extra: dev
Requires-Dist: pre-commit==4.6.1; extra == 'dev'
Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
Requires-Dist: pytest==9.0.3; extra == 'dev'
Requires-Dist: ruff==0.16.1; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
    <img alt="FSQ — Fully Self Quality" src="docs/assets/logo-light.svg" width="320">
  </picture>
</p>

<h3 align="center">Describe what to test. Let AI help to test the user flow.</h3>

<p align="center">Describe the goal and let AI operate the real app. FSQ records evidence and turns the exploration into a test you can review and replay.</p>

<p align="center">An open-source project from <a href="https://github.com/FSQ-lab">FSQ Lab</a>.</p>

<p align="center">
  <a href="https://github.com/FSQ-lab/FSQ/actions/workflows/ci.yml"><img src="https://github.com/FSQ-lab/FSQ/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11 or newer"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT license"></a>
  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Alpha status">
</p>

<p align="center">
  <a href="https://fsq-lab.github.io/FSQ/">Website</a> ·
  <a href="#quick-start">Quick start</a> ·
  <a href="README.zh-CN.md">中文</a> ·
  <a href="docs/getting-started.md">Guide</a> ·
  <a href="CONTRIBUTING.md">Contribute</a>
</p>

## See FSQ in action

https://github.com/user-attachments/assets/aa9d0a12-2f93-4894-8349-52a013424939

[Watch the full demo on YouTube](https://youtu.be/QqCahxGDdS0).

## How it works

1. **Describe:** You define the platform and target, goal, success criteria, and allowed and forbidden actions.
2. **Observe** as AI tests the real UI flow and FSQ captures screenshots, interface state, events, and may produce a reviewable test.
3. **Control** what happens next: inspect the evidence and, if FSQ returns a test, inspect it unchanged before separately requesting any deterministic replay.

You get an evidence-backed result and, when FSQ returns one, a portable, reusable test you can review, keep, and replay without surrendering control.

## Quick start

Start with the real outcome you want to test. You need Python 3.11+ and the [prerequisites for your platform and target](docs/platform-prerequisites.md). Choose one of the two paths below. Enter Provider credentials only in the FSQ UI—not in Coding Agent chat. Review the result first and, if FSQ returns a Case, review it unchanged before separately requesting any replay.

### 1. Coding Agent

**Initial setup.** Open your project in a Coding Agent and paste:
> The official FSQ project is https://github.com/FSQ-lab/FSQ. Establish the exact opened project root. Batch the read-only Python, `fsq`, and Skill-presence checks with their exact working directories, commands, purpose, and effects. Then request one approval for the listed changes, covering only installation or upgrade of `fsq-agent` and one `fsq init --agent skill` in this project; disclose the exact commands and Python-environment and project-file effects before asking. Perform only the approved operations, verify `fsq`, and report the exact installed Skill path. This one-time setup does not initialize a Workspace, configure a Provider, or run a test. Tell me to reload or start a new Coding Agent session, then stop.

Complete that reload before continuing.

**First test.** Copy this prompt into your Coding Agent:
> Use FSQ to test this user goal: launch Microsoft Edge Stable, use Bing to search for `FSQ GitHub`, then inspect the organic search results and report the current position/ranking of the FSQ GitHub repository. Select the Web platform and Microsoft Edge Stable. Follow the installed FSQ Skill and ask only for decisions it cannot establish.

Treat the platform and exact target as facts or user-owned decisions: provide them when asked rather than letting the agent guess a target ID or path, and do not substitute a different Edge channel.

Review the result first. If FSQ returns a Case, review it unchanged before deciding whether to request replay separately.

### 2. FSQ UI

**Initial setup.**

```bash
python -m pip install --upgrade fsq-agent
fsq ui
```

Choose **Quick Test** for exploration using the automatic `~/.fsq/quick-test/` Workspace, or **FSQ Case Manager** for Workspace/Case management, history, and Strict Replay. Both share **Settings**, where you configure the FSQ LLM Provider and explicitly select a model.

1. Select the platform and, where applicable, the device or browser.
2. Describe what to do and verify. For Web, provide a URL or a clear search goal, for example: `Search FSQ on GitHub and find its official website.` You do not need to know the result URL beforehand.
3. Select **Start Quick Test**. The model identifies the application; FSQ validates the resolved target and environment before exploration. Unresolved intent, zero/multiple lookup results, and preparation failures stop the request without a follow-up dialogue. Target availability does not prove the model understood the application correctly.
4. Review the result and evidence using **Open report**, or choose **New test**. Quick Test does not save Cases; in Case Manager, review any generated Case unchanged before separately requesting replay.

![FSQ Test Runner for describing a test goal](docs/media/01-describe-goal.png)

[Detailed first-test guide](docs/getting-started.md)

## Platforms

FSQ supports Web, Android, Windows, and macOS targets; see [platform prerequisites](docs/platform-prerequisites.md), and help broaden support through [contributions](CONTRIBUTING.md).

> [!IMPORTANT]
> FSQ is alpha software for evaluation and contribution. Evidence is stored locally and can contain visible application data or other private target data. Review it before sharing, and do not commit evidence or credentials. Public interfaces may evolve before 1.0; see [support and stability](docs/support-and-stability.md).

## Documentation

- [Getting started](docs/getting-started.md)
- [中文快速开始](docs/getting-started.zh-CN.md)
- [CLI reference](docs/cli-reference.md)
- [FSQ Case format](docs/case-format.md)
- [Advanced Codex compatibility](docs/codex-integration.md)
- [Platform prerequisites](docs/platform-prerequisites.md)
- [Support and stability](docs/support-and-stability.md)

## Built by FSQ Lab and the community

Built by [FSQ Lab](https://github.com/FSQ-lab) with thanks to [all contributors](https://github.com/FSQ-lab/FSQ/graphs/contributors). Want to help? Read [CONTRIBUTING.md](CONTRIBUTING.md) and join us.

## License

[MIT](LICENSE) — Copyright (c) Microsoft Corporation.
