fhir-validator-wrapper 1.1.0 → 1.2.0

package/fhir-validator.js

@@ -1,6 +1,8 @@
 const { spawn } = require('child_process');
 const http = require('http');
 const https = require('https');
+const fs = require('fs');
+const path = require('path');
 const { URL } = require('url');
 
 /**
@@ -14,11 +16,14 @@ class FhirValidator {
    */
   constructor(validatorJarPath, logger = null) {
     this.validatorJarPath = validatorJarPath;
-    this.logger = logger; // Store the logger
+    this.logger = logger;
     this.process = null;
     this.port = null;
     this.baseUrl = null;
     this.isReady = false;
+
+    // Version tracking file sits alongside the JAR
+    this.versionFilePath = validatorJarPath + '.version';
   }
 
   /**
@@ -38,10 +43,8 @@ class FhirValidator {
    */
   log(level, message, meta = {}) {
     if (this.logger) {
-      // Use the Winston logger if available
       this.logger[level](message, meta);
     } else {
-      // Fall back to console
       if (level === 'error') {
         console.error(message, meta);
       } else if (level === 'warn') {
@@ -52,6 +55,248 @@ class FhirValidator {
     }
   }
 
+  /**
+   * Get the latest release information from GitHub
+   * @returns {Promise<{version: string, downloadUrl: string}>}
+   */
+  async getLatestRelease() {
+    return new Promise((resolve, reject) => {
+      const options = {
+        hostname: 'api.github.com',
+        path: '/repos/hapifhir/org.hl7.fhir.core/releases/latest',
+        method: 'GET',
+        headers: {
+          'User-Agent': 'fhir-validator-node',
+          'Accept': 'application/vnd.github.v3+json'
+        }
+      };
+
+      const req = https.request(options, (res) => {
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`GitHub API returned status ${res.statusCode}: ${data}`));
+            return;
+          }
+
+          try {
+            const release = JSON.parse(data);
+            const version = release.tag_name;
+
+            // Find the validator_cli.jar asset
+            const asset = release.assets.find(a => a.name === 'validator_cli.jar');
+            if (!asset) {
+              reject(new Error('validator_cli.jar not found in latest release assets'));
+              return;
+            }
+
+            resolve({
+              version,
+              downloadUrl: asset.browser_download_url,
+              publishedAt: release.published_at
+            });
+          } catch (error) {
+            reject(new Error(`Failed to parse GitHub response: ${error.message}`));
+          }
+        });
+      });
+
+      req.on('error', reject);
+      req.setTimeout(30000, () => {
+        req.destroy();
+        reject(new Error('GitHub API request timeout'));
+      });
+
+      req.end();
+    });
+  }
+
+  /**
+   * Get the currently installed version
+   * @returns {string|null} - The installed version or null if not installed
+   */
+  getInstalledVersion() {
+    try {
+      if (fs.existsSync(this.versionFilePath)) {
+        const versionInfo = JSON.parse(fs.readFileSync(this.versionFilePath, 'utf8'));
+        return versionInfo.version;
+      }
+    } catch (error) {
+      this.log('warn', `Failed to read version file: ${error.message}`);
+    }
+    return null;
+  }
+
+  /**
+   * Save version information
+   * @param {string} version - The version string
+   * @param {string} downloadUrl - The URL it was downloaded from
+   */
+  saveVersionInfo(version, downloadUrl) {
+    const versionInfo = {
+      version,
+      downloadUrl,
+      downloadedAt: new Date().toISOString()
+    };
+    fs.writeFileSync(this.versionFilePath, JSON.stringify(versionInfo, null, 2));
+  }
+
+  /**
+   * Download a file from a URL, following redirects
+   * @param {string} url - The URL to download from
+   * @param {string} destPath - The destination file path
+   * @returns {Promise<void>}
+   */
+  async downloadFile(url, destPath) {
+    return new Promise((resolve, reject) => {
+      const downloadWithRedirects = (downloadUrl, redirectCount = 0) => {
+        if (redirectCount > 5) {
+          reject(new Error('Too many redirects'));
+          return;
+        }
+
+        const parsedUrl = new URL(downloadUrl);
+        const protocol = parsedUrl.protocol === 'https:' ? https : http;
+
+        const req = protocol.get(downloadUrl, {
+          headers: {
+            'User-Agent': 'fhir-validator-node'
+          }
+        }, (res) => {
+          // Handle redirects
+          if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+            this.log('info', `Following redirect to ${res.headers.location}`);
+            downloadWithRedirects(res.headers.location, redirectCount + 1);
+            return;
+          }
+
+          if (res.statusCode !== 200) {
+            reject(new Error(`Download failed with status ${res.statusCode}`));
+            return;
+          }
+
+          // Ensure directory exists
+          const dir = path.dirname(destPath);
+          if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+          }
+
+          // Download to a temp file first, then rename
+          const tempPath = destPath + '.download';
+          const fileStream = fs.createWriteStream(tempPath);
+
+          const contentLength = parseInt(res.headers['content-length'], 10);
+          let downloadedBytes = 0;
+          let lastLoggedPercent = 0;
+
+          res.on('data', (chunk) => {
+            downloadedBytes += chunk.length;
+            if (contentLength) {
+              const percent = Math.floor((downloadedBytes / contentLength) * 100);
+              if (percent >= lastLoggedPercent + 10) {
+                this.log('info', `Download progress: ${percent}% (${Math.round(downloadedBytes / 1024 / 1024)}MB / ${Math.round(contentLength / 1024 / 1024)}MB)`);
+                lastLoggedPercent = percent;
+              }
+            }
+          });
+
+          res.pipe(fileStream);
+
+          fileStream.on('finish', () => {
+            fileStream.close(() => {
+              // Rename temp file to final destination
+              fs.renameSync(tempPath, destPath);
+              resolve();
+            });
+          });
+
+          fileStream.on('error', (err) => {
+            // Clean up temp file on error
+            if (fs.existsSync(tempPath)) {
+              fs.unlinkSync(tempPath);
+            }
+            reject(err);
+          });
+        });
+
+        req.on('error', reject);
+        req.setTimeout(300000, () => { // 5 minute timeout for large file
+          req.destroy();
+          reject(new Error('Download timeout'));
+        });
+      };
+
+      downloadWithRedirects(url);
+    });
+  }
+
+  /**
+   * Ensure the validator JAR is downloaded and up to date
+   * @param {Object} [options] - Options for the update check
+   * @param {boolean} [options.force=false] - Force download even if current version is up to date
+   * @param {boolean} [options.skipUpdateCheck=false] - Skip checking for updates if JAR exists
+   * @returns {Promise<{version: string, updated: boolean, downloaded: boolean}>}
+   */
+  async ensureValidator(options = {}) {
+    const { force = false, skipUpdateCheck = false } = options;
+
+    const jarExists = fs.existsSync(this.validatorJarPath);
+    const installedVersion = this.getInstalledVersion();
+
+    // If JAR exists and we're skipping update checks, we're done
+    if (jarExists && skipUpdateCheck && !force) {
+      this.log('info', `Using existing validator JAR (version check skipped)`);
+      return {
+        version: installedVersion || 'unknown',
+        updated: false,
+        downloaded: false
+      };
+    }
+
+    // Check for latest version
+    this.log('info', 'Checking for latest FHIR validator release...');
+    const latest = await this.getLatestRelease();
+    this.log('info', `Latest version: ${latest.version}`);
+
+    // Determine if we need to download
+    const needsDownload = force ||
+      !jarExists ||
+      !installedVersion ||
+      installedVersion !== latest.version;
+
+    if (!needsDownload) {
+      this.log('info', `Validator is up to date (${installedVersion})`);
+      return {
+        version: installedVersion,
+        updated: false,
+        downloaded: false
+      };
+    }
+
+    // Download the JAR
+    if (installedVersion && jarExists) {
+      this.log('info', `Updating validator from ${installedVersion} to ${latest.version}...`);
+    } else {
+      this.log('info', `Downloading validator ${latest.version}...`);
+    }
+
+    await this.downloadFile(latest.downloadUrl, this.validatorJarPath);
+    this.saveVersionInfo(latest.version, latest.downloadUrl);
+
+    this.log('info', `Validator ${latest.version} downloaded successfully`);
+
+    return {
+      version: latest.version,
+      updated: installedVersion !== null && installedVersion !== latest.version,
+      downloaded: true
+    };
+  }
+
   /**
    * Start the FHIR validator service
    * @param {Object} config - Configuration object
@@ -61,6 +306,8 @@ class FhirValidator {
    * @param {string[]} [config.igs] - Array of implementation guide packages (e.g., ["hl7.fhir.us.core#6.0.0"])
    * @param {number} [config.port=8080] - Port to run the service on
    * @param {number} [config.timeout=30000] - Timeout in ms to wait for service to be ready
+   * @param {boolean} [config.autoDownload=true] - Automatically download/update validator JAR
+   * @param {boolean} [config.skipUpdateCheck=false] - Skip checking for updates if JAR exists
    * @returns {Promise<void>}
    */
   async start(config) {
@@ -68,12 +315,28 @@ class FhirValidator {
       throw new Error('Validator service is already running');
     }
 
-    const { version, txServer, txLog, igs = [], port = 8080, timeout = 30000 } = config;
+    const {
+      version,
+      txServer,
+      txLog,
+      igs = [],
+      port = 8080,
+      timeout = 30000,
+      autoDownload = true,
+      skipUpdateCheck = false
+    } = config;
 
     if (!version || !txServer || !txLog) {
       throw new Error('version, txServer, and txLog are required');
     }
 
+    // Ensure validator is downloaded if autoDownload is enabled
+    if (autoDownload) {
+      await this.ensureValidator({ skipUpdateCheck });
+    } else if (!fs.existsSync(this.validatorJarPath)) {
+      throw new Error(`Validator JAR not found at ${this.validatorJarPath}. Set autoDownload: true or download manually.`);
+    }
+
     this.port = port;
     this.baseUrl = `http://localhost:${port}`;
 
@@ -82,7 +345,7 @@ class FhirValidator {
       '-jar', this.validatorJarPath,
       '-server', port.toString(),
       '-tx', txServer,
-      '-txlog', txLog,
+      '-txLog', txLog,
       '-version', version
     ];
 
@@ -115,7 +378,7 @@ class FhirValidator {
       lines.forEach(line => {
         // Remove ANSI escape sequences (color codes, etc.)
         const cleanLine = line.replace(/\u001b\[[0-9;]*m/g, '').trim();
-        if (cleanLine.length > 1) { // Only log non-empty lines
+        if (cleanLine.length > 1) {
           this.log('info', `Validator: ${cleanLine}`);
         }
       });
@@ -366,6 +629,132 @@ class FhirValidator {
     });
   }
 
+  /**
+   * Run a terminology server test
+   * @param {Object} params - Test parameters
+   * @param {string} params.server - The address of the terminology server to test
+   * @param {string} params.suiteName - The suite name that contains the test to run
+   * @param {string} params.testName - The test name to run
+   * @param {string} params.version - What FHIR version to use for the test
+   * @param {string} [params.externalFile] - Optional name of messages file
+   * @param {string} [params.modes] - Optional comma delimited string of modes
+   * @returns {Promise<{result: boolean, message?: string}>}
+   */
+  async runTxTest(params) {
+    if (!this.isReady) {
+      throw new Error('Validator service is not ready');
+    }
+
+    const { server, suiteName, testName, version, externalFile, modes } = params;
+
+    if (!server || !suiteName || !testName || !version) {
+      throw new Error('server, suiteName, testName, and version are required');
+    }
+
+    // Build query parameters
+    const queryParams = new URLSearchParams();
+    queryParams.set('server', server);
+    queryParams.set('suite', suiteName);
+    queryParams.set('test', testName);
+    queryParams.set('version', version);
+
+    if (externalFile) {
+      queryParams.set('externalFile', externalFile);
+    }
+    if (modes) {
+      queryParams.set('modes', modes);
+    }
+
+    const url = `${this.baseUrl}/txTest?${queryParams.toString()}`;
+
+    return new Promise((resolve) => {
+      const parsedUrl = new URL(url);
+      const requestOptions = {
+        hostname: parsedUrl.hostname,
+        port: parsedUrl.port,
+        path: parsedUrl.pathname + parsedUrl.search,
+        method: 'GET',
+        headers: {
+          'Accept': 'application/fhir+json'
+        }
+      };
+
+      const req = http.request(requestOptions, (res) => {
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          // Handle HTTP errors
+          if (res.statusCode >= 400) {
+            resolve({
+              result: false,
+              message: `HTTP error ${res.statusCode}: ${data}`
+            });
+            return;
+          }
+
+          try {
+            const outcome = JSON.parse(data);
+
+            // Check if it's a valid OperationOutcome
+            if (outcome.resourceType !== 'OperationOutcome') {
+              resolve({
+                result: false,
+                message: `Unexpected response type: ${outcome.resourceType || 'unknown'}`
+              });
+              return;
+            }
+
+            // No issues means success
+            if (!outcome.issue || outcome.issue.length === 0) {
+              resolve({ result: true });
+              return;
+            }
+
+            // Check for error severity issues
+            const errorIssue = outcome.issue.find(issue => issue.severity === 'error');
+            if (errorIssue) {
+              resolve({
+                result: false,
+                message: errorIssue.details?.text || errorIssue.diagnostics || 'Test failed with error'
+              });
+              return;
+            }
+
+            // No error issues, test passed
+            resolve({ result: true });
+
+          } catch (error) {
+            resolve({
+              result: false,
+              message: `Failed to parse response: ${error.message}`
+            });
+          }
+        });
+      });
+
+      req.on('error', (error) => {
+        resolve({
+          result: false,
+          message: `Request failed: ${error.message}`
+        });
+      });
+
+      req.setTimeout(60000, () => {
+        req.destroy();
+        resolve({
+          result: false,
+          message: 'Request timeout'
+        });
+      });
+
+      req.end();
+    });
+  }
+
   /**
    * Stop the validator service
    * @returns {Promise<void>}
@@ -383,19 +772,16 @@ class FhirValidator {
         }
         this.cleanup();
         resolve();
-      }, 10000); // 10 second total timeout
+      }, 10000);
 
-      // Single exit handler
       const onExit = () => {
         clearTimeout(timeout);
         this.cleanup();
         resolve();
       };
 
-      this.process.once('exit', onExit); // Use 'once' to avoid duplicate listeners
+      this.process.once('exit', onExit);
 
-      // Since Java process is blocking on System.in.read(), SIGTERM likely won't work
-      // Go straight to SIGKILL for immediate termination
       this.log('info', 'Stopping validator process...');
       this.process.kill('SIGKILL');
     });
@@ -421,4 +807,4 @@ class FhirValidator {
   }
 }
 
-module.exports = FhirValidator;
+module.exports = FhirValidator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-validator-wrapper",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Node.js wrapper for the HL7 FHIR Validator CLI",
   "main": "fhir-validator.js",
   "scripts": {

package/readme.md

@@ -30,13 +30,22 @@ There are many ways to contribute:
 
 ## Overview
 
-This library manages the lifecycle of the FHIR Validator Java service and provides a clean Node.js interface for validation operations. It handles process management, HTTP communication, and provides typed validation options.
+This library manages the lifecycle of the FHIR Validator Java service and provides a clean Node.js interface for validation operations. It handles automatic downloading of the validator JAR, process management, HTTP communication, and provides typed validation options.
+
+## Features
+
+- **Automatic JAR Management**: Automatically downloads and updates the FHIR Validator CLI JAR from GitHub releases
+- **Version Tracking**: Tracks installed version and checks for updates
+- **Resource Validation**: Validate FHIR resources in JSON or XML format
+- **Profile Validation**: Validate against specific FHIR profiles
+- **Implementation Guide Support**: Load IGs at startup or runtime
+- **Terminology Testing**: Run terminology server tests with `runTxTest`
 
 ## Prerequisites
 
 - Node.js 12.0.0 or higher
 - Java 8 or higher
-- FHIR Validator CLI JAR file (download from [GitHub releases](https://github.com/hapifhir/org.hl7.fhir.core/releases))
+- Internet connection (for automatic JAR download, or manually download from [GitHub releases](https://github.com/hapifhir/org.hl7.fhir.core/releases))
 
 ## Installation
 
@@ -46,21 +55,15 @@ npm install fhir-validator-wrapper
 
 ## Quick Start
 
-```bash
-# Run the example with your JAR file
-FHIR_VALIDATOR_JAR_PATH=./your-validator.jar npm start
-```
-
-Or in code:
-
 ```javascript
 const FhirValidator = require('fhir-validator-wrapper');
 
 async function validateResource() {
+  // The JAR will be automatically downloaded if not present
   const validator = new FhirValidator('./validator_cli.jar');
   
   try {
-    // Start the validator service
+    // Start the validator service (auto-downloads JAR if needed)
     await validator.start({
       version: '5.0.0',
       txServer: 'http://tx.fhir.org/r5',
@@ -89,14 +92,62 @@ async function validateResource() {
 
 ### Constructor
 
-#### `new FhirValidator(validatorJarPath)`
+#### `new FhirValidator(validatorJarPath, logger)`
 
 Creates a new FHIR validator instance.
 
-- `validatorJarPath` (string): Path to the FHIR validator CLI JAR file
+- `validatorJarPath` (string): Path to the FHIR validator CLI JAR file (will be downloaded here if not present)
+- `logger` (Object, optional): Winston logger instance for custom logging
 
 ### Methods
 
+#### `ensureValidator(options)`
+
+Checks for and downloads/updates the validator JAR as needed. This is called automatically by `start()` when `autoDownload` is enabled.
+
+**Parameters:**
+- `options` (Object, optional): Configuration object
+  - `force` (boolean): Force download even if current version is up to date (default: false)
+  - `skipUpdateCheck` (boolean): Skip checking for updates if JAR exists (default: false)
+
+**Returns:** `Promise<{version: string, updated: boolean, downloaded: boolean}>`
+
+**Example:**
+```javascript
+const validator = new FhirValidator('./validator_cli.jar');
+
+// Check for updates and download if needed
+const result = await validator.ensureValidator();
+console.log(`Version: ${result.version}`);
+console.log(`Downloaded: ${result.downloaded}`);
+console.log(`Updated: ${result.updated}`);
+
+// Force re-download
+await validator.ensureValidator({ force: true });
+
+// Skip update check (use existing JAR)
+await validator.ensureValidator({ skipUpdateCheck: true });
+```
+
+#### `getLatestRelease()`
+
+Fetches the latest release information from GitHub.
+
+**Returns:** `Promise<{version: string, downloadUrl: string, publishedAt: string}>`
+
+**Example:**
+```javascript
+const latest = await validator.getLatestRelease();
+console.log(`Latest version: ${latest.version}`);
+console.log(`Published: ${latest.publishedAt}`);
+```
+
+#### `getInstalledVersion()`
+
+Gets the currently installed validator version.
+
+**Returns:** `string|null` - The installed version or null if not installed
+
 #### `start(config)`
 
 Starts the FHIR validator service with the specified configuration.
@@ -109,6 +160,8 @@ Starts the FHIR validator service with the specified configuration.
   - `igs` (string[], optional): Array of implementation guide packages
   - `port` (number, optional): Port to run the service on (default: 8080)
   - `timeout` (number, optional): Startup timeout in milliseconds (default: 30000)
+  - `autoDownload` (boolean, optional): Automatically download/update validator JAR (default: true)
+  - `skipUpdateCheck` (boolean, optional): Skip checking for updates if JAR exists (default: false)
 
 **Returns:** `Promise<void>`
 
@@ -122,7 +175,9 @@ await validator.start({
     'hl7.fhir.us.core#6.0.0',
     'hl7.fhir.uv.sdc#3.0.0'
   ],
-  port: 8080
+  port: 8080,
+  autoDownload: true,      // Download JAR if missing (default)
+  skipUpdateCheck: true    // Don't check for updates every time
 });
 ```
 
@@ -193,6 +248,47 @@ Loads an additional implementation guide at runtime.
 await validator.loadIG('hl7.fhir.uv.ips', '1.1.0');
 ```
 
+#### `runTxTest(params)`
+
+Runs a terminology server test against a specified server.
+
+**Parameters:**
+- `params` (Object): Test parameters
+  - `server` (string): The address of the terminology server to test
+  - `suiteName` (string): The suite name that contains the test to run
+  - `testName` (string): The test name to run
+  - `version` (string): What FHIR version to use for the test
+  - `externalFile` (string, optional): Name of messages file
+  - `modes` (string, optional): Comma delimited string of modes
+
+**Returns:** `Promise<{result: boolean, message?: string}>`
+
+**Example:**
+```javascript
+// Run a terminology server test
+const result = await validator.runTxTest({
+  server: 'http://tx-dev.fhir.org',
+  suiteName: 'metadata',
+  testName: 'metadata',
+  version: '5.0'
+});
+
+if (result.result) {
+  console.log('Test passed!');
+} else {
+  console.log('Test failed:', result.message);
+}
+
+// With optional parameters
+const result = await validator.runTxTest({
+  server: 'http://tx-dev.fhir.org',
+  suiteName: 'expand',
+  testName: 'expand-test-1',
+  version: '5.0',
+  modes: 'lenient,tx-resource-cache'
+});
+```
+
 #### `stop()`
 
 Stops the validator service and cleans up resources.
@@ -211,6 +307,79 @@ Performs a health check on the running service.
 
 **Returns:** `Promise<void>`
 
+## Automatic JAR Download
+
+The library automatically manages the FHIR Validator CLI JAR file:
+
+### Default Behavior
+When you call `start()`, the library will:
+1. Check if the JAR file exists at the specified path
+2. If missing, download the latest version from GitHub releases
+3. Track the version in a `.version` file alongside the JAR
+
+### Version Tracking
+Version information is stored in `{jarPath}.version`:
+```json
+{
+  "version": "6.3.4",
+  "downloadUrl": "https://github.com/hapifhir/org.hl7.fhir.core/releases/...",
+  "downloadedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### Update Strategies
+
+```javascript
+// Always check for updates (default)
+await validator.start({
+  version: '5.0.0',
+  txServer: 'http://tx.fhir.org/r5',
+  txLog: './txlog.txt'
+});
+
+// Skip update check for faster startup
+await validator.start({
+  version: '5.0.0',
+  txServer: 'http://tx.fhir.org/r5',
+  txLog: './txlog.txt',
+  skipUpdateCheck: true
+});
+
+// Disable auto-download entirely (JAR must exist)
+await validator.start({
+  version: '5.0.0',
+  txServer: 'http://tx.fhir.org/r5',
+  txLog: './txlog.txt',
+  autoDownload: false
+});
+```
+
+### Manual Download Management
+
+```javascript
+const validator = new FhirValidator('./validator_cli.jar');
+
+// Check what's available vs installed
+const latest = await validator.getLatestRelease();
+const installed = validator.getInstalledVersion();
+
+console.log(`Latest: ${latest.version}`);
+console.log(`Installed: ${installed || 'not installed'}`);
+
+// Download/update without starting service
+const result = await validator.ensureValidator();
+
+// Force re-download
+await validator.ensureValidator({ force: true });
+```
+
+### Download-Only Mode
+
+```bash
+# Use the example script to just download/update the JAR
+node example.js --download-only
+```
+
 ## Implementation Guide Loading
 
 Implementation guides can be loaded in two ways:
@@ -297,6 +466,14 @@ await validator.start({
 });
 ```
 
+5. **Skip Update Checks in CI/CD**: For faster builds, skip update checks:
+```javascript
+await validator.start({
+  // ... other config
+  skipUpdateCheck: true
+});
+```
+
 ## Testing
 
 The library includes comprehensive tests. You can run them in different ways depending on your setup:
@@ -306,51 +483,59 @@ The library includes comprehensive tests. You can run them in different ways dep
 npm run test:unit
 ```
 
-### Integration Tests (requires JAR file)
+### GitHub API Tests (requires network)
 ```bash
-# Set the JAR path and run integration tests
-FHIR_VALIDATOR_JAR_PATH=./your-validator.jar npm run test:integration
+GITHUB_API_TESTS=1 npm test
 ```
 
-### Manual Testing
+### Download Tests (downloads ~300MB JAR)
 ```bash
-# Quick manual test with your JAR
-FHIR_VALIDATOR_JAR_PATH=./your-validator.jar npm run test:manual
+DOWNLOAD_TESTS=1 npm test
 ```
 
-### Configuration
-
-The JAR file location can be configured using the `FHIR_VALIDATOR_JAR_PATH` environment variable:
-
+### Integration Tests (requires JAR file and network)
 ```bash
-# Option 1: Set environment variable
-export FHIR_VALIDATOR_JAR_PATH=/path/to/your/validator.jar
-npm test
+# With auto-download
+INTEGRATION_TESTS=1 npm test
 
-# Option 2: Inline with command
-FHIR_VALIDATOR_JAR_PATH=./validator_cli.jar npm test
-
-# Option 3: Use npm script helper
-npm run test:with-jar
+# With specific JAR path
+FHIR_VALIDATOR_JAR_PATH=./your-validator.jar INTEGRATION_TESTS=1 npm test
 ```
 
-**Default behavior**: If no environment variable is set, tests will look for `./validator_cli.jar`
+### Manual Testing
+```bash
+# Quick manual test (auto-downloads JAR if needed)
+INTEGRATION_TESTS=1 npm run test:manual
+```
 
 ## Troubleshooting
 
 ### Common Issues
 
 1. **Java not found**: Ensure Java is installed and available in PATH
-2. **JAR file not found**: Verify the validator JAR path is correct
+2. **JAR download fails**: Check internet connection and GitHub accessibility
 3. **Port conflicts**: Change the port if 8080 is already in use
 4. **Memory issues**: Add JVM options by modifying the spawn command if needed
 5. **Network timeouts**: Increase timeout values for slow networks
+6. **GitHub rate limits**: Use `skipUpdateCheck: true` to avoid repeated API calls
 
 ### Debug Logging
 
-The library logs validator stdout/stderr for debugging. Check console output for Java process messages.
+The library logs validator stdout/stderr for debugging. You can provide a Winston logger for custom logging:
+
+```javascript
+const winston = require('winston');
+const logger = winston.createLogger({
+  level: 'debug',
+  transports: [new winston.transports.Console()]
+});
+
+const validator = new FhirValidator('./validator_cli.jar', logger);
+// Or set later:
+validator.setLogger(logger);
+```
 
 ## Support
 
 For issues with this wrapper, please file a GitHub issue.
-For FHIR validator issues, see the [official FHIR validator documentation](https://confluence.hl7.org/spaces/FHIR/pages/35718580/Using+the+FHIR+Validator).
+For FHIR validator issues, see the [official FHIR validator documentation](https://confluence.hl7.org/spaces/FHIR/pages/35718580/Using+the+FHIR+Validator).