Skip to content

Commit a5370e3

Browse files
Ripwordsclaude
Ripwords
and
claude
committed
docs: add non-technical "Filing a bug report" guide
A reporter-facing page that walks testers through filing a report from the embed widget and via the Chrome extension, without assuming familiarity with project keys, allowed-origins, or service workers. The existing extension.md stays as the technical reference and links across to the new page. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent b965ccb commit a5370e3

3 files changed

Lines changed: 160 additions & 0 deletions

File tree

‎docs/.vitepress/config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,10 @@ export default defineConfig({
3636
{ text: "Architecture", link: "/guide/architecture" },
3737
],
3838
},
39+
{
40+
text: "For testers",
41+
items: [{ text: "Filing a bug report", link: "/guide/filing-reports" }],
42+
},
3943
{
4044
text: "Web SDK",
4145
items: [{ text: "Embed + API", link: "/guide/sdk" }],

‎docs/guide/extension.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44

55
It does not replace the `<script>` embed. Real users on customer sites always get the SDK through the embed; the extension is for internal testers only.
66

7+
::: tip Looking for the end-user guide?
8+
This page is the technical reference. If you're a **tester** who just needs to install the extension and file bug reports, see [**Filing a bug report**](/guide/filing-reports) instead — same content, written for non-technical readers.
9+
:::
10+
711
## When to use it
812

913
Reach for the extension when:

‎docs/guide/filing-reports.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Filing a bug report
2+
3+
This guide is for **anyone reporting a bug** through Repro — whether you're a tester, a designer, a customer-success agent, or just clicked the little widget at the corner of a page. No coding required.
4+
5+
## What you'll see on a page
6+
7+
When Repro is set up on a website, a small floating button appears in a corner of the page (usually bottom-right). Click it to start a report.
8+
9+
If you don't see the button on a site you're testing, you probably need the [Chrome extension](#using-the-chrome-extension-for-testers) — that's covered below.
10+
11+
## Filing a report — step by step
12+
13+
### 1. Click the launcher button
14+
15+
The widget opens and asks if you want to capture a screenshot of the current page. Say yes — Chrome may show a "Share this tab?" prompt; pick the current tab and click **Share**.
16+
17+
::: tip
18+
The screenshot captures the page exactly as you see it. Open the menu, scroll to the bug, hover over the broken thing — *then* click the launcher. Whatever's on screen is what gets captured.
19+
:::
20+
21+
### 2. Annotate the screenshot
22+
23+
A toolbar appears over the screenshot. Use it to point out what's wrong:
24+
25+
| Tool | When to use it |
26+
| --- | --- |
27+
| **Pen / Freehand** | Circle a button, scribble around an area |
28+
| **Arrow** | Point at one specific thing |
29+
| **Rectangle** | Frame a section ("everything in this box is wrong") |
30+
| **Text** | Write a short label like "should say 'Save' not 'Submut'" |
31+
| **Color picker** | Switch to red/yellow/etc. so your annotations stand out |
32+
| **Undo / Redo** | Take back a stroke |
33+
| **Clear** | Wipe all annotations and start over |
34+
35+
You don't need to be neat. A messy circle around the broken button is more useful than a perfectly aligned rectangle.
36+
37+
### 3. Describe what went wrong
38+
39+
You'll see a short form:
40+
41+
- **Title** — one line, like "Save button doesn't work on the profile page".
42+
- **Description** — what you expected vs. what actually happened. Two or three sentences is usually enough.
43+
- **Severity** (if shown) — pick one. "Blocker" = nobody can use the feature. "Minor" = annoying but workable.
44+
- **Your email or name** (if shown) — so the developer can ping you with questions.
45+
46+
::: tip Writing a good description
47+
Three things make a report easy to fix:
48+
1. **What you tried to do** — "I clicked Save after editing my display name."
49+
2. **What happened** — "The page reloaded but my name didn't change."
50+
3. **What you expected** — "I expected the new name to show up in the header."
51+
52+
That's it. You don't need to guess the cause.
53+
:::
54+
55+
### 4. Click Send
56+
57+
The report is uploaded along with:
58+
59+
- Your annotated screenshot
60+
- A 30-second replay of what you were doing right before you clicked the launcher (so the developer can *see* the bug happen)
61+
- Browser console logs and network errors
62+
- Your browser, OS, screen size, and the page URL
63+
64+
You'll get a "Report sent" confirmation. The widget closes. You can keep using the page.
65+
66+
The developer who triages the report has everything they need to reproduce — you don't need to write a 10-step repro guide.
67+
68+
## Privacy — what's captured, what isn't
69+
70+
The 30-second replay records what changed on the page (clicks, scrolls, inputs you filled in). A few things are **automatically scrubbed**:
71+
72+
- **Passwords** — every `<input type="password">` is masked. Your password never rides along.
73+
- **Anything the site marks as private** — developers can tag fields like credit card numbers or SSNs to mask them. Ask your team if you're not sure.
74+
- **Cookies on a denylist** — session tokens, auth cookies, etc. are redacted by default.
75+
76+
If you're worried about something specific, **don't type it in before clicking Send**. The replay only covers the last 30 seconds before you clicked the launcher.
77+
78+
## Using the Chrome extension (for testers)
79+
80+
Some sites won't have the widget yet — usually because the developers haven't installed it, or because you're testing a third-party site. For those, the **Repro Tester** Chrome extension lets you run the widget anyway.
81+
82+
### Install the extension
83+
84+
Easiest way: install from the Chrome Web Store.
85+
86+
> 🧩 [**Repro Tester on the Chrome Web Store**](https://chromewebstore.google.com/detail/repro-tester/kiedhhobipcjkgiljemcmmmnfcbcmjbg)
87+
88+
Click **Add to Chrome**. Pin the icon to your toolbar (click the puzzle-piece icon → pin Repro Tester) so you can find it.
89+
90+
### Set up the site you want to test
91+
92+
You need to add the site to the extension once. Your team admin should give you four things:
93+
94+
| What | What it looks like |
95+
| --- | --- |
96+
| **Site address** | `https://staging.acme.com` (whatever site you're testing) |
97+
| **Project key** | Starts with `rp_pk_` and has a long string of letters/numbers |
98+
| **Dashboard address** | `https://feedback.yourcompany.com` (where reports go) |
99+
| **Label** | Anything you'll recognize, like `staging` or `customer demo` |
100+
101+
If you don't have these, ask whoever set up Repro at your company.
102+
103+
Steps:
104+
105+
1. Click the extension icon in your toolbar.
106+
2. Click **+ New origin**.
107+
3. Fill in the four fields above.
108+
4. Click **Add origin**.
109+
5. Chrome shows a permission prompt — click **Allow** for both the site and the dashboard.
110+
6. Open a new tab on the site you just added. The Repro launcher button appears in the corner.
111+
112+
You're done — file reports the same way as on any other site.
113+
114+
### Common problems
115+
116+
**"I added the site but the launcher doesn't show up"**
117+
Open the extension popup. If your site card has an amber stripe saying "Permission required", click **Grant** and accept Chrome's prompt.
118+
119+
**"It says 'Origin not allowed' when I send a report"**
120+
Your dashboard admin needs to add the site to the project's allowed-origins list. Send them the URL of the page you're testing.
121+
122+
**"The screen-share prompt didn't appear / hangs"**
123+
On macOS, Chrome needs screen-recording permission. Open **System Settings → Privacy & Security → Screen Recording**, turn it on for Chrome, and restart Chrome.
124+
125+
**"I want to remove a site I added"**
126+
Open the extension popup, find the site card, click the three-dot menu, choose **Remove**.
127+
128+
### Removing the extension
129+
130+
`chrome://extensions` → Repro Tester → **Remove**. All your saved sites and permissions are deleted at the same time.
131+
132+
## FAQ
133+
134+
**Do I need an account to file reports?**
135+
No. The widget works without you logging in. If your team has identity turned on, the page passes your name automatically — you don't have to type it.
136+
137+
**Will my coworkers see my report?**
138+
Anyone with access to the dashboard project will see reports filed against that project. Your team controls who has access.
139+
140+
**Can I attach extra files (logs, screenshots, videos)?**
141+
Yes — the description field accepts pasted images, and the dashboard's comment thread on each report supports drag-and-drop attachments after the report is filed.
142+
143+
**Does it work on mobile?**
144+
The widget itself works in mobile browsers. For native iOS/Android apps, your developers need the [Expo SDK](/guide/expo) — the Chrome extension only helps on desktop Chrome.
145+
146+
**The page is on `localhost` — does Repro work there?**
147+
Yes, both for the embed widget and the Chrome extension. Just add the localhost URL (with port) when configuring the extension.
148+
149+
## Need more help?
150+
151+
- **Stuck on a step?** Ask the person who set up Repro at your company — they'll know your specific dashboard URL and project keys.
152+
- **Found a bug in Repro itself?** [Open an issue on GitHub](https://github.com/Ripwords/ReproJs/issues).

0 commit comments

Comments
 (0)