From 862f926bd52ab2bfb3924bc8f3b282ab556d0a93 Mon Sep 17 00:00:00 2001
From: Jeremiah Russell <jerry@jrussell.ie>
Date: Mon, 20 Oct 2025 07:02:51 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20document=20how=20to=20ru?=
 =?UTF-8?q?n=20the=20ignored=20Gmail=20integration=20test=20locally?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/README.md b/README.md
index a80ccbd..551a3d7 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,23 @@ The `cull-gmail` provides a software library and command line program to enable
 - move email matching a filtered list to trash
 ## cull-gmail Library Documentation
 
+### Running the optional Gmail integration test
+
+An optional, ignored integration test exercises the Gmail API end-to-end (networked). It is ignored by default and will not run in CI.
+
+Steps to run locally:
+
+1. Ensure you have valid OAuth client credentials configured for the library (see `ClientConfig::builder()` usage in docs).
+2. Run the test explicitly with the ignored flag:
+
+```bash
+cargo test --test gmail_message_list_integration -- --ignored
+```
+
+Notes:
+- The test performs a lightweight listing (max 10 messages) and should be safe, but it still uses your Gmail account.
+- Do not run this in CI; it is intended only for local verification.
+
 The `cull-gmail` library provides types to enable the culling of emails using the Gmail API including the following steps:
 - login to get authorization
 - backup the mailbox