feat(smarts3): Add local smarts3 testing support and documentation

readme.md

@@ -1024,6 +1024,82 @@ pnpm run build
 pnpm test
 ```
 
+## 🧪 Testing with smarts3
+
+smartregistry works seamlessly with [@push.rocks/smarts3](https://code.foss.global/push.rocks/smarts3), a local S3-compatible server for testing. This allows you to test the registry without needing cloud credentials or external services.
+
+### Quick Start with smarts3
+
+```typescript
+import { Smarts3 } from '@push.rocks/smarts3';
+import { SmartRegistry } from '@push.rocks/smartregistry';
+
+// Start local S3 server
+const s3Server = await Smarts3.createAndStart({
+  server: { port: 3456 },
+  storage: { cleanSlate: true },
+});
+
+// Manually create IS3Descriptor matching smarts3 configuration
+// Note: smarts3 v5.1.0 doesn't properly expose getS3Descriptor() yet
+const s3Descriptor = {
+  endpoint: 'localhost',
+  port: 3456,
+  accessKey: 'test',
+  accessSecret: 'test',
+  useSsl: false,
+  region: 'us-east-1',
+};
+
+// Create registry with smarts3 configuration
+const registry = new SmartRegistry({
+  storage: {
+    ...s3Descriptor,
+    bucketName: 'my-test-registry',
+  },
+  auth: {
+    jwtSecret: 'test-secret',
+    tokenStore: 'memory',
+    npmTokens: { enabled: true },
+    ociTokens: {
+      enabled: true,
+      realm: 'https://auth.example.com/token',
+      service: 'my-registry',
+    },
+  },
+  npm: { enabled: true, basePath: '/npm' },
+  oci: { enabled: true, basePath: '/oci' },
+  pypi: { enabled: true, basePath: '/pypi' },
+  cargo: { enabled: true, basePath: '/cargo' },
+});
+
+await registry.init();
+
+// Use registry...
+// Your tests here
+
+// Cleanup
+await s3Server.stop();
+```
+
+### Benefits of Testing with smarts3
+
+- ✅ **Zero Setup** - No cloud credentials or external services needed
+- ✅ **Fast** - Local filesystem storage, no network latency
+- ✅ **Isolated** - Clean slate per test run, no shared state
+- ✅ **CI/CD Ready** - Works in automated pipelines without configuration
+- ✅ **Full Compatibility** - Implements S3 API, works with IS3Descriptor
+
+### Running Integration Tests
+
+```bash
+# Run smarts3 integration test
+pnpm exec tstest test/test.integration.smarts3.node.ts --verbose
+
+# Run all tests (includes smarts3)
+pnpm test
+```
+
 ## License and Legal Information
 
 This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.