Add test_graphql_comments management command for easy setup verification

This commit adds a Django management command that simplifies testing and
verification of GraphQL SQLCommenter setup, as requested for the quickstart
guide.

New Features:
- Management command: python manage.py test_graphql_comments
  - Checks configuration (middleware, settings, paths)
  - Sets test GraphQL metadata
  - Executes test SQL query
  - Analyzes queries for GraphQL comments
  - Reports success/failure with troubleshooting tips

- Command options:
  - --operation-name: Test with custom operation name
  - --query-type: Test different types (query/mutation/subscription)
  - --verbose: Show full SQL queries in output

Documentation Updates:
- Simplified quickstart guide to feature the management command
- Moved advanced testing methods to API Reference
- Added "Quick Test" section to Troubleshooting guide
- Updated Example README to include management command

Testing:
- 15 comprehensive tests with 100% coverage of management command
- All 96 tests pass across Python 3.9, 3.11, and 3.13
- Overall project coverage increased from 91% to 95%

The management command provides a simple, single-command way to verify
GraphQL SQL commenting is working correctly, improving the developer
experience during initial setup.

Author: SmileyChris

docs/getting-started/quickstart.md

@@ -101,64 +101,42 @@ You'll need at least Django 3.2+ and Python 3.8+. If you want subscription suppo
     SQLCOMMENTER_WITH_SUBSCRIPTIONS = True
     ```
 
-## 3. Test Locally
+## 3. Test It Works
 
-### Start Django
+Verify your setup with the built-in test command:
 
 ```bash
-python manage.py runserver
+python manage.py test_graphql_comments
 ```
 
-### Send GraphQL Request
-
-```bash
-curl -X POST http://localhost:8000/graphql \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "query getUserProfile { user(id: 1) { username } }",
-    "operationName": "getUserProfile"
-  }'
-```
-
-### Check SQL Comments
-
-```python title="Django shell or view"
-from django.db import connection
-from django.test.utils import override_settings
-
-with override_settings(DEBUG=True):
-    # Execute your GraphQL query
-    # Then check:
-    for query in connection.queries:
-        print(query['sql'])
-
-# Should see:
-# SELECT * FROM auth_user WHERE id = 1
-# /*framework=django:4.2,graphql_op=getUserProfile,graphql_type=query,graphql_sha=abc123*/
+**Example output:**
 ```
+=== GraphQL SQLCommenter Test ===
 
-## 4. Verify It Works
+1. Checking configuration...
+   ✓ GraphQL commenting enabled
+   ✓ GraphQL paths: /graphql
+   ✓ SqlCommenterMiddleware found
 
-Create a test view:
+2. Setting test GraphQL metadata...
+   ✓ Metadata set: op=testOperation, type=query
 
-```python title="your_app/views.py"
-from django.http import JsonResponse
-from django.db import connection
-from graphql_sqlcommenter.context import get_graphql_meta
+3. Executing test database query...
+   ✓ Executed 1 SQL query(ies)
 
+4. Analyzing SQL comments...
+   ✓ Query 1: Found all GraphQL metadata
 
-def test_graphql_meta(request):
-    """Debug view to check GraphQL metadata."""
-    meta = get_graphql_meta()
-    return JsonResponse({
-        'metadata': meta,
-        'recent_queries': [q['sql'] for q in connection.queries[-5:]]
-    })
+✓ SUCCESS: GraphQL comments are working!
 ```
 
-Execute a GraphQL query, then hit this endpoint to verify metadata was captured.
+!!! note "More Testing Options"
+    For advanced testing methods (Django shell, unit tests, debug views, etc.), see the [API Reference - Testing section](../reference/api.md#testing-with-management-command).
+
+!!! warning "Test Failed?"
+    If the test fails, see the [Troubleshooting Guide](../reference/troubleshooting.md) for detailed debugging steps.
 
-## 5. Deploy to Staging
+## 4. Deploy to Staging
 
 ```bash
 # Commit changes
@@ -176,7 +154,7 @@ git push staging main
 # - Filter: graphql_op='getUserProfile'
 ```
 
-## 6. Production Rollout
+## 5. Production Rollout
 
 Add feature flag for gradual rollout:
 

docs/reference/api.md

@@ -128,6 +128,64 @@ curl -X POST http://localhost:8000/graphql \
 
 **Location:** `graphql_sqlcommenter.middleware.SqlCommenterMiddleware`
 
+## Management Commands
+
+### `test_graphql_comments`
+
+Django management command to test GraphQL SQL comment functionality.
+
+```bash
+python manage.py test_graphql_comments
+```
+
+**What it does:**
+
+1. ✓ Checks configuration (middleware, settings, paths)
+2. ✓ Sets test GraphQL metadata
+3. ✓ Executes a test SQL query
+4. ✓ Analyzes queries for GraphQL comments
+5. ✓ Reports success/failure with troubleshooting tips
+
+**Options:**
+
+```bash
+# Test with custom operation name
+python manage.py test_graphql_comments --operation-name myCustomOp
+
+# Test different operation types
+python manage.py test_graphql_comments --query-type mutation
+python manage.py test_graphql_comments --query-type subscription
+
+# Show verbose output with actual SQL queries
+python manage.py test_graphql_comments --verbose
+```
+
+**Example output:**
+
+```
+=== GraphQL SQLCommenter Test ===
+
+1. Checking configuration...
+   ✓ GraphQL commenting enabled
+   ✓ GraphQL paths: /graphql
+   ✓ SqlCommenterMiddleware found
+
+2. Setting test GraphQL metadata...
+   ✓ Metadata set: op=testOperation, type=query
+
+3. Executing test database query...
+   ✓ Executed 1 SQL query(ies)
+
+4. Analyzing SQL comments...
+   ✓ Query 1: Found all GraphQL metadata
+
+✓ SUCCESS: GraphQL comments are working!
+```
+
+**Location:** `graphql_sqlcommenter.management.commands.test_graphql_comments`
+
+---
+
 ## Django App Configuration
 
 ### `GraphQLSQLCommenterConfig`
@@ -345,20 +403,96 @@ users = User.objects.all()
 # SQL: SELECT * FROM auth_user /*graphql_op=customQuery,...*/
 ```
 
-### Testing
+### Testing with Management Command
+
+```bash
+# Quick test
+python manage.py test_graphql_comments
+
+# Test specific operation type
+python manage.py test_graphql_comments --query-type mutation --verbose
+```
+
+### Testing with Real GraphQL Queries
+
+```bash
+# Start Django
+python manage.py runserver
+
+# Send GraphQL request
+curl -X POST http://localhost:8000/graphql \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "query getUserProfile { user(id: 1) { username } }",
+    "operationName": "getUserProfile"
+  }'
+
+# Check logs for SQL comments
+```
+
+### Testing in Django Shell
+
+```python
+from django.db import connection
+from django.test.utils import override_settings
+from graphql_sqlcommenter import set_graphql_meta
+
+# Enable query logging
+with override_settings(DEBUG=True):
+    # Set metadata
+    set_graphql_meta("testOp", "query", "test123")
+
+    # Execute query
+    from django.contrib.auth.models import User
+    User.objects.first()
+
+    # Check queries
+    for query in connection.queries:
+        print(query['sql'])
+    # Should see: /*graphql_op=testOp,graphql_type=query,graphql_sha=test123*/
+```
+
+### Testing in Unit Tests
 
 ```python
 from graphql_sqlcommenter import set_graphql_meta, get_graphql_meta, clear_graphql_meta
+from django.test.utils import CaptureQueriesContext
+from django.db import connection
 
-# Set test metadata
-set_graphql_meta("testOp", "query", "test123")
+def test_graphql_comments():
+    # Set test metadata
+    set_graphql_meta("testOp", "query", "test123")
 
-# Verify
-meta = get_graphql_meta()
-assert meta['op'] == "testOp"
+    # Verify metadata is set
+    meta = get_graphql_meta()
+    assert meta['op'] == "testOp"
 
-# Clean up
-clear_graphql_meta()
+    # Capture queries
+    with CaptureQueriesContext(connection) as queries:
+        User.objects.first()
+
+    # Verify comment
+    assert 'graphql_op=testOp' in queries[0]['sql']
+
+    # Clean up
+    clear_graphql_meta()
+```
+
+### Testing Debug View
+
+```python
+# Create a debug view to inspect metadata
+from django.http import JsonResponse
+from django.db import connection
+from graphql_sqlcommenter.context import get_graphql_meta
+
+def debug_graphql_metadata(request):
+    """Debug view to check GraphQL metadata."""
+    meta = get_graphql_meta()
+    return JsonResponse({
+        'metadata': meta,
+        'recent_queries': [q['sql'] for q in connection.queries[-5:]]
+    })
 ```
 
 ## Version

docs/reference/troubleshooting.md

@@ -2,6 +2,29 @@
 
 Common issues and solutions for GraphQL SQLCommenter.
 
+## Quick Test
+
+Before diving into troubleshooting, use the built-in test command:
+
+```bash
+python manage.py test_graphql_comments
+```
+
+This will check your configuration and verify that SQL comments are working. Options:
+
+```bash
+# Test with custom operation name
+python manage.py test_graphql_comments --operation-name myCustomOp
+
+# Test different operation types
+python manage.py test_graphql_comments --query-type mutation
+
+# See verbose output with actual SQL queries
+python manage.py test_graphql_comments --verbose
+```
+
+If the test succeeds but you still don't see comments in your application, continue with the troubleshooting steps below.
+
 ## SQL Comments Not Appearing
 
 ### Issue: No comments in SQL queries

example/README.md

@@ -33,6 +33,16 @@ MIDDLEWARE = [
 
 ### 3. Test it
 
+**Quick test with management command:**
+
+```bash
+python manage.py test_graphql_comments
+```
+
+This command will verify your configuration and test that SQL comments are working correctly.
+
+**Or test with a real GraphQL request:**
+
 ```bash
 # Run your GraphQL query
 curl -X POST http://localhost:8000/graphql \