Skip to content

Refresh public README and landing page with Android Quick Test demo #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
houlianpi merged 2 commits into from
Oct 20, 2026
Merged

Refresh public README and landing page with Android Quick Test demo #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fdaed25
feat(website): refresh public demo and Quick Test onboarding
houlianpi Oct 20, 2026
f4e3e32
test(docs): align public onboarding contracts with Quick Test
houlianpi Oct 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 69 additions & 35 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
</picture>
</p>

<h3 align="center">Describe what to test. Let AI help to test the user flow.</h3>
<h3 align="center">Describe a goal. Test the real app.</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">Describe what to do and what should happen. Let AI operate the real app and verify the outcome. Inspect screenshots, actions, and results to see what happened.</p>

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

Expand All @@ -27,64 +27,100 @@
<a href="CONTRIBUTING.md">Contribute</a>
</p>

## See FSQ in action
## See a complete test

https://github.com/user-attachments/assets/aa9d0a12-2f93-4894-8349-52a013424939
https://github.com/user-attachments/assets/3acfecf4-bf48-4c76-8245-2eeef0dedb1f

[Watch the full demo on YouTube](https://youtu.be/QqCahxGDdS0).
[![Android Quick Test cover showing a real device browser and FSQ execution evidence](docs/media/quick-test-poster.png)](https://youtu.be/f1sobvVHNg0)

## How it works
[Watch on YouTube](https://youtu.be/f1sobvVHNg0) · [English captions](docs/media/quick-test.en.srt) · [Media sources and review status](docs/media/quick-test-demo-provenance.md)

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.
The video shows one real Android Quick Test: find the FSQ repository, follow its About website link, and verify both homepage headlines. You can start with Web; platform setup and execution differ, and search results and outcomes can vary.

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

**Describe the journey and the checks.** Find `FSQ-lab/FSQ`, follow its About website link, and verify `Describe a goal.` and `Test the real app.`. The card adds editorial explanation around a recorded goal; the surrounding text is separate from the product UI.

![Editorial task card with a real Quick Test goal: search for the repository, follow About to its website, and check both headlines](docs/media/quick-test-task.png)

**Watch AI operate the real app.** The Android browser screen sits beside the FSQ action timeline, connecting execution with captured screenshots and interface state.

![Real FSQ execution capture showing the action timeline beside the Android browser device view](docs/media/quick-test-execution.png)

**Check the result against the evidence.** The captured page shows both required headlines. The same Run reports execution success, verification success, and complete evidence separately. The card pairs real page and report captures with editorial explanation.

![Editorial result card pairing the captured homepage headlines with the same Run report showing execution and verification success and complete evidence](docs/media/quick-test-result.png)

## 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.
Choose **Coding Agent** or **FSQ UI**. Both lead to one Quick Test and evidence review. You need Python 3.11+, a supported configured Provider and explicitly selected model, and [platform prerequisites](docs/platform-prerequisites.md). Enter Provider credentials privately in local FSQ Settings; never paste them into Coding Agent chat.

Quick Test prepares `~/.fsq/quick-test/` automatically. It requires no manual project Workspace setup, does not save a formal Case, and does not perform Strict Replay.

### Coding Agent

Add the FSQ Skill, reload your Coding Agent, and ask it to run the complete goal below with FSQ Quick Test.

<details>
<summary>Expand: one-time setup and first run</summary>

### 1. Coding Agent
Open your project in the Coding Agent and paste:

**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.
> The official FSQ project is https://github.com/FSQ-lab/FSQ. Establish the exact opened project root. Batch and disclose read-only Python, fsq, and Skill-presence checks with their working directories, commands, purpose, and effects. Request one approval covering only installation or upgrade of fsq-agent and one fsq init --agent skill in this project; show exact commands and Python-environment and project-file effects first. Perform only approved operations, verify fsq, and report the installed Skill path. This setup does not initialize a Workspace, configure a Provider, or run a test. Ask me to reload or start a new Coding Agent session, then stop.

Complete that reload before continuing.
After reloading, select Web and an available browser, then send “Use FSQ Quick Test for the following goal” with the complete goal. Follow the installed Skill: it discovers readiness, asks for unresolved decisions, and reports actual progress and evidence. After a package upgrade, rerun `fsq init --agent skill` and reload to update the copied Skill.

**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.
</details>

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.
[Open Coding Agent setup guide](docs/getting-started.md#coding-agent)

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

### 2. FSQ UI
Install FSQ, open the local UI, choose **Quick Test**, and paste the same goal.

**Initial setup.**
<details>
<summary>Expand: install and start Quick Test</summary>

```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. Configure a supported Provider and explicitly select a model in **Settings**.
2. Return to **Quick Test**, select Web and an available browser, and paste the goal below.
3. Select **Start Quick Test**. FSQ interprets the app and validates the target and environment before testing. Unresolved intent, zero or multiple target matches, or preparation failure stop the request without follow-up dialogue.
4. Use **Open report** to inspect the outcome and evidence. Target availability does not prove the model understood the intended app correctly.

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.
</details>

![FSQ Test Runner for describing a test goal](docs/media/01-describe-goal.png)
[Open FSQ UI setup guide](docs/getting-started.md#fsq-ui)

[Detailed first-test guide](docs/getting-started.md)
### Try a complete user journey

## Platforms
Web is an accessible first-use option; the recording shows Android. After selecting a browser, copy this complete goal into either entry path:

FSQ supports Web, Android, Windows, and macOS targets; see [platform prerequisites](docs/platform-prerequisites.md), and help broaden support through [contributions](CONTRIBUTING.md).
```text
Use the selected browser to search for the FSQ-lab/FSQ GitHub repository. Open that repository, follow the website link in its About section, and verify that the destination page displays both “Describe a goal.” and “Test the real app.” Report the outcome with the captured page evidence. Only browse public pages. Do not sign in, change repository content, or submit forms. Stop and report a blocker if the repository or About website link cannot be identified.
```

After the run, inspect the report and captured page evidence. Treat failed, inconclusive, or preparation-error outcomes as observed; they do not mean the checks passed.

## Go further when you need to

- **Inspect the run:** review screenshots, interface state, events, and reports to compare actual behavior with your expectations.
- **Manage reusable Cases:** use **FSQ Case Manager** for registered Workspaces, explicit Case creation or saving an available candidate, and run history. A run may produce a Case; generation is conditional.
- **Choose deterministic replay:** review any returned Case unchanged, then separately request Strict Replay. Replay operates the target again and requires prerequisite and side-effect checks; Quick Test never runs it automatically.

FSQ supports Web, Android, Windows, and macOS targets, subject to [platform prerequisites](docs/platform-prerequisites.md).

## Help shape FSQ

If FSQ is useful to you, [visit the repository and Star FSQ](https://github.com/FSQ-lab/FSQ) to help others discover it. Tried it? [Share your experience](https://github.com/FSQ-lab/FSQ/issues/new/choose): what worked, where you got stuck, and what you want to test next.

Include the FSQ version, platform, sanitized goal, expected and actual outcome, and only reviewed diagnostic excerpts. Remove credentials, personal data, private URLs, paths, and device identifiers before sharing screenshots or logs. Report security issues through [Security](SECURITY.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).
> FSQ is alpha software for evaluation and contribution. Evidence is stored locally and may contain private app data; review it before sharing, and do not commit evidence or credentials. AI operations send necessary provider-bound inputs to your configured Provider. Public interfaces may evolve before 1.0; see [support and stability](docs/support-and-stability.md).

## Documentation

Expand All @@ -94,11 +130,9 @@ FSQ supports Web, Android, Windows, and macOS targets; see [platform prerequisit
- [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
- [Contribute](CONTRIBUTING.md)

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.
Built by [FSQ Lab](https://github.com/FSQ-lab) and the community, with thanks to [all contributors](https://github.com/FSQ-lab/FSQ/graphs/contributors).

## License

Expand Down
Loading
Loading