From 11e02fdfea28634ec5680fe4bcae8cd6ce66ee03 Mon Sep 17 00:00:00 2001
From: icepaq <62949848+icepaq@users.noreply.github.com>
Date: Tue, 6 Jan 2026 13:09:32 -0500
Subject: [PATCH] beta testing guide (#444)

* beta install guide

* Update README.md
---
 .gitignore                 |  3 +-
 README.md                  |  2 ++
 docs/beta-testing-ff146.md | 64 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 docs/beta-testing-ff146.md

diff --git a/.gitignore b/.gitignore
index 70b1d5c..d7747ed 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,4 +45,5 @@ closedsrc
 
 .venv
 bundle
-*.pem
\ No newline at end of file
+*.pem
+.DS_store
diff --git a/README.md b/README.md
index 084612c..705c853 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,8 @@ Camoufox is the most modern, effective & future-proof open source solution for a
 ## <span style="color:yellow">Firefox Version Upgrade Notice</span>
 The current main branch is built for Firefox v146. It is an experimental change and may contain several bugs. If you are building from source and require a stable production version, use branch `releases/135`.
 
+See the [Beta Testing Guide](docs/beta-testing-ff146.md) for instructions on testing FF146.
+
 ---
 
 ## Sponsors
diff --git a/docs/beta-testing-ff146.md b/docs/beta-testing-ff146.md
new file mode 100644
index 0000000..fc8810f
--- /dev/null
+++ b/docs/beta-testing-ff146.md
@@ -0,0 +1,64 @@
+# Testing Firefox 146 Beta
+
+This guide explains how to test the experimental Firefox 146 build of Camoufox.
+
+> **Note:** The FF146 build is experimental and may contain bugs. For a stable production version, use branch `releases/135`.
+
+## Build from Source
+
+1. Clone the repository:
+```bash
+git clone --depth 1 https://github.com/daijro/camoufox
+cd camoufox
+```
+
+2. Set up the build environment:
+```bash
+make dir
+make bootstrap   # only needed once
+```
+
+3. Build for your target platform:
+```bash
+python3 multibuild.py --target <os> --arch <arch>
+```
+
+| Parameter | Options |
+|-----------|---------|
+| `--target` | `linux`, `windows`, `macos` |
+| `--arch` | `x86_64`, `arm64`, `i686` |
+
+Build artifacts will appear in the `dist/` folder.
+
+### Default Install Directories
+
+When using the Python library (`camoufox fetch`), the default install directory is:
+
+| OS | Install Directory |
+|------|-------------------|
+| **Linux** | `~/.cache/camoufox/` |
+| **macOS** | `~/Library/Caches/camoufox/` |
+| **Windows** | `C:\Users\<user>\AppData\Local\camoufox\camoufox\Cache\` |
+
+## Replacing the Binary
+
+To test FF146 with an existing Camoufox installation:
+
+1. Build from source using the instructions above
+2. Extract the built zip from `dist/`
+3. Replace the binary at the corresponding path for your OS:
+
+**Linux:**
+```bash
+cp /path/to/built/camoufox-bin ~/.cache/camoufox/camoufox-bin
+```
+
+**macOS:**
+```bash
+cp /path/to/built/Camoufox.app ~/Library/Caches/camoufox/Camoufox.app
+```
+
+**Windows:**
+```powershell
+copy C:\path\to\built\camoufox.exe C:\Users\<user>\AppData\Local\camoufox\camoufox\Cache\camoufox.exe
+```