📝 docs: document how to run the ignored Gmail integration test locally

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