fix(test): make integration tests opt-in

- Gate e2e/functional suites behind RUN_INTEGRATION_TESTS

- Fix README code-fence rendering and doc links

- Replace console usage in CLI help with stdout/stderr writes

Author: joachimBrindeau

README.md

@@ -264,7 +264,6 @@ Then configure with absolute path:
 ### As MCP Server
 
 Once configured, you have access to 10 powerful tools
-```
 
 ### Programmatic Usage
 
@@ -359,14 +358,17 @@ npm run build
 ### Run Tests
 
 ```bash
-# All tests
+# Default test run (integration tests are skipped unless explicitly enabled)
 npm test
 
+# Integration tests (requires network access + Dynadot credentials)
+RUN_INTEGRATION_TESTS=true DYNADOT_API_KEY=your-api-key TEST_DOMAIN=your-domain.com npm test
+
 # E2E tests (validates all 106 API endpoints)
-TEST_DOMAIN=your-domain.com npm test -- test/e2e.test.ts
+RUN_INTEGRATION_TESTS=true TEST_DOMAIN=your-domain.com npm test -- test/e2e.test.ts
 
 # Functional tests (real CRUD operations)
-TEST_DOMAIN=your-domain.com npm test -- test/functional.test.ts
+RUN_INTEGRATION_TESTS=true TEST_DOMAIN=your-domain.com npm test -- test/functional.test.ts
 
 # Watch mode
 npm run test:watch

docs/environment.md

@@ -25,7 +25,7 @@ Get your API key from: https://www.dynadot.com/account/domain/setting/api.html?s
 
 **Recommendation**: Set to `true` when testing read-only operations. Some write operations (like `create_contact`) are not supported in sandbox mode.
 
-**⚠️ Sandbox Limitations**: The Dynadot sandbox does not support all API commands. Specifically, `create_contact` fails in sandbox mode. For complete details, see [SANDBOX_LIMITATIONS.md](./SANDBOX_LIMITATIONS.md).
+**⚠️ Sandbox Limitations**: The Dynadot sandbox does not support all API commands. Specifically, `create_contact` fails in sandbox mode. For complete details, see [sandbox.md](./sandbox.md).
 
 ### TEST_DOMAIN
 

docs/testing.md

@@ -16,7 +16,7 @@ npm run test:all-tools:write
 
 1. **Set Environment Variables**:
 
-   Create a `.env` file in the project root (see [ENVIRONMENT.md](./ENVIRONMENT.md) for details):
+   Create a `.env` file in the project root (see [environment.md](./environment.md) for details):
 
    ```bash
    # Required
@@ -292,7 +292,7 @@ TEST_FOLDER_ID=-1
 EOF
 ```
 
-See [ENVIRONMENT.md](./ENVIRONMENT.md) for detailed documentation on all environment variables.
+See [environment.md](./environment.md) for detailed documentation on all environment variables.
 
 ### Build Errors
 

src/index.ts

@@ -11,28 +11,36 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
 
+function writeStdoutLine(line: string): void {
+  process.stdout.write(`${line}\n`);
+}
+
+function writeStderrLine(line: string): void {
+  process.stderr.write(`${line}\n`);
+}
+
 function showHelp(): never {
-  console.log(`domain-mcp v${packageJson.version}`);
-  console.log('');
-  console.log('A Domain MCP server for AI-powered Dynadot domain management.');
-  console.log('');
-  console.log('This is not a CLI tool - it runs as an MCP server via stdin/stdout.');
-  console.log('');
-  console.log('Setup instructions:');
-  console.log(`  ${GITHUB_URL}#quick-installation`);
-  console.log('');
-  console.log('Example configuration:');
-  console.log(JSON.stringify(EXAMPLE_CONFIG, null, 2));
+  writeStdoutLine(`domain-mcp v${packageJson.version}`);
+  writeStdoutLine('');
+  writeStdoutLine('A Domain MCP server for AI-powered Dynadot domain management.');
+  writeStdoutLine('');
+  writeStdoutLine('This is not a CLI tool - it runs as an MCP server via stdin/stdout.');
+  writeStdoutLine('');
+  writeStdoutLine('Setup instructions:');
+  writeStdoutLine(`  ${GITHUB_URL}#quick-installation`);
+  writeStdoutLine('');
+  writeStdoutLine('Example configuration:');
+  writeStdoutLine(JSON.stringify(EXAMPLE_CONFIG, null, 2));
   process.exit(0);
 }
 
 function showUsageAndExit(): never {
-  console.error('domain-mcp is an MCP server, not a CLI tool.');
-  console.error('');
-  console.error('Run with --help for usage information.');
-  console.error('');
-  console.error('Quick start:');
-  console.error(`  ${GITHUB_URL}#quick-installation`);
+  writeStderrLine('domain-mcp is an MCP server, not a CLI tool.');
+  writeStderrLine('');
+  writeStderrLine('Run with --help for usage information.');
+  writeStderrLine('');
+  writeStderrLine('Quick start:');
+  writeStderrLine(`  ${GITHUB_URL}#quick-installation`);
   process.exit(1);
 }
 
@@ -42,7 +50,7 @@ if (args.includes('--help') || args.includes('-h')) {
 }
 
 if (args.includes('--version') || args.includes('-v')) {
-  console.log(packageJson.version);
+  writeStdoutLine(packageJson.version);
   process.exit(0);
 }
 

test/e2e.test.ts

@@ -3,6 +3,8 @@ import { getClient } from '../src/client.js';
 
 const TEST_DOMAIN = process.env.TEST_DOMAIN;
 const client = getClient();
+const isIntegrationEnabled = process.env.RUN_INTEGRATION_TESTS === 'true';
+const describeIntegration = describe.runIf(isIntegrationEnabled);
 
 // Helper to extract status from nested response
 // Dynadot API has multiple response formats:
@@ -38,19 +40,21 @@ function hasValidResponse(result: Record<string, unknown>): boolean {
   return false;
 }
 
-beforeAll(() => {
-  if (!TEST_DOMAIN) {
-    throw new Error('TEST_DOMAIN environment variable is required (e.g., example.com)');
-  }
-  if (!process.env.DYNADOT_API_KEY) {
-    throw new Error('DYNADOT_API_KEY environment variable is required');
-  }
+describeIntegration('Integration test prerequisites', () => {
+  beforeAll(() => {
+    if (!TEST_DOMAIN) {
+      throw new Error('TEST_DOMAIN environment variable is required (e.g., example.com)');
+    }
+    if (!process.env.DYNADOT_API_KEY) {
+      throw new Error('DYNADOT_API_KEY environment variable is required');
+    }
+  });
 });
 
 // =============================================================================
 // TOOL 1: dynadot_domain (11 actions)
 // =============================================================================
-describe('dynadot_domain', () => {
+describeIntegration('dynadot_domain', () => {
   describe('read operations', () => {
     it('list - should list all domains', async () => {
       const result = await client.execute('list_domain');
@@ -137,7 +141,7 @@ describe('dynadot_domain', () => {
 // =============================================================================
 // TOOL 2: dynadot_domain_settings (13 actions)
 // =============================================================================
-describe('dynadot_domain_settings', () => {
+describeIntegration('dynadot_domain_settings', () => {
   describe('read operations', () => {
     it('get_ns - should get nameservers', async () => {
       const result = await client.execute('get_ns', { domain: TEST_DOMAIN });
@@ -245,7 +249,7 @@ describe('dynadot_domain_settings', () => {
 // =============================================================================
 // TOOL 3: dynadot_dns (5 actions)
 // =============================================================================
-describe('dynadot_dns', () => {
+describeIntegration('dynadot_dns', () => {
   describe('read operations', () => {
     it('get - should get DNS records', async () => {
       const result = await client.execute('get_dns', { domain: TEST_DOMAIN });
@@ -289,7 +293,7 @@ describe('dynadot_dns', () => {
 // =============================================================================
 // TOOL 4: dynadot_nameserver (6 actions)
 // =============================================================================
-describe('dynadot_nameserver', () => {
+describeIntegration('dynadot_nameserver', () => {
   describe('read operations', () => {
     it('list - should list registered nameservers', async () => {
       const result = await client.execute('server_list');
@@ -334,7 +338,7 @@ describe('dynadot_nameserver', () => {
 // =============================================================================
 // TOOL 5: dynadot_transfer (8 actions)
 // =============================================================================
-describe('dynadot_transfer', () => {
+describeIntegration('dynadot_transfer', () => {
   describe('read operations', () => {
     it('status - should get transfer status', async () => {
       const result = await client.execute('get_transfer_status', { domain: TEST_DOMAIN });
@@ -392,7 +396,7 @@ describe('dynadot_transfer', () => {
 // =============================================================================
 // TOOL 6: dynadot_contact (11 actions)
 // =============================================================================
-describe('dynadot_contact', () => {
+describeIntegration('dynadot_contact', () => {
   describe('read operations', () => {
     it('list - should list all contacts', async () => {
       const result = await client.execute('contact_list');
@@ -475,7 +479,7 @@ describe('dynadot_contact', () => {
 // =============================================================================
 // TOOL 7: dynadot_folder (15 actions)
 // =============================================================================
-describe('dynadot_folder', () => {
+describeIntegration('dynadot_folder', () => {
   describe('read operations', () => {
     it('list - should list all folders', async () => {
       const result = await client.execute('folder_list');
@@ -592,7 +596,7 @@ describe('dynadot_folder', () => {
 // =============================================================================
 // TOOL 8: dynadot_account (13 actions)
 // =============================================================================
-describe('dynadot_account', () => {
+describeIntegration('dynadot_account', () => {
   describe('read operations', () => {
     it('info - should get account info', async () => {
       const result = await client.execute('account_info');
@@ -682,7 +686,7 @@ describe('dynadot_account', () => {
 // =============================================================================
 // TOOL 9: dynadot_aftermarket (20 actions)
 // =============================================================================
-describe('dynadot_aftermarket', () => {
+describeIntegration('dynadot_aftermarket', () => {
   describe('backorders', () => {
     it('backorder_list - should list backorder requests', async () => {
       const result = await client.execute('backorder_request_list');
@@ -838,7 +842,7 @@ describe('dynadot_aftermarket', () => {
 // =============================================================================
 // TOOL 10: dynadot_order (5 actions)
 // =============================================================================
-describe('dynadot_order', () => {
+describeIntegration('dynadot_order', () => {
   describe('read operations', () => {
     it('list - should list recent orders', async () => {
       const today = new Date();

test/functional.test.ts

@@ -3,21 +3,25 @@ import { getClient } from '../src/client.js';
 
 const TEST_DOMAIN = process.env.TEST_DOMAIN;
 const client = getClient();
-
-beforeAll(() => {
-  if (!TEST_DOMAIN) {
-    throw new Error('TEST_DOMAIN environment variable is required');
-  }
-  if (!process.env.DYNADOT_API_KEY) {
-    throw new Error('DYNADOT_API_KEY environment variable is required');
-  }
+const isIntegrationEnabled = process.env.RUN_INTEGRATION_TESTS === 'true';
+const describeIntegration = describe.runIf(isIntegrationEnabled);
+
+describeIntegration('Integration test prerequisites', () => {
+  beforeAll(() => {
+    if (!TEST_DOMAIN) {
+      throw new Error('TEST_DOMAIN environment variable is required');
+    }
+    if (!process.env.DYNADOT_API_KEY) {
+      throw new Error('DYNADOT_API_KEY environment variable is required');
+    }
+  });
 });
 
 // =============================================================================
 // FUNCTIONAL TESTS - Actually verify operations work end-to-end
 // =============================================================================
 
-describe('Functional: Folder CRUD', () => {
+describeIntegration('Functional: Folder CRUD', () => {
   const testFolderName = `test-folder-${Date.now()}`;
   let createdFolderId: string | null = null;
 
@@ -86,7 +90,7 @@ describe('Functional: Folder CRUD', () => {
   });
 });
 
-describe('Functional: Contact CRUD', () => {
+describeIntegration('Functional: Contact CRUD', () => {
   const testContactName = `Test Contact ${Date.now()}`;
   let createdContactId: string | null = null;
 
@@ -198,7 +202,7 @@ describe('Functional: Contact CRUD', () => {
   });
 });
 
-describe('Functional: Domain Note', () => {
+describeIntegration('Functional: Domain Note', () => {
   const testNote = `Functional test note ${Date.now()}`;
 
   it('1. should set a note on the domain', async () => {
@@ -245,7 +249,7 @@ describe('Functional: Domain Note', () => {
 // Note: Dynadot API has a confusing error message for lock_domain unlock:
 // When trying to unlock, it returns "this domain has been locked already" (wrong message)
 // This appears to be domain protection or an API bug - unlock may not work via API
-describe('Functional: Domain Lock/Unlock', () => {
+describeIntegration('Functional: Domain Lock/Unlock', () => {
   let initialLockState: string | null = null;
 
   it('1. should get current lock state', async () => {
@@ -302,7 +306,7 @@ describe('Functional: Domain Lock/Unlock', () => {
   });
 });
 
-describe('Functional: Renewal Option', () => {
+describeIntegration('Functional: Renewal Option', () => {
   let initialRenewOption: string | null = null;
 
   it('1. should get current renewal option', async () => {