feat(examples): add SDK source coverage collection for example tests (#259)

- Add test-with-sdk-coverage script to collect coverage from core SDK
source
- Copy SDK source to src/dur-sdk/ before tests via copy-sdk-source.js
script
- Configure Jest module mapper to resolve SDK imports to local source
copy
- Add coverage-to-csv script to export coverage data as CSV file
- Update .gitignore to exclude dur-sdk folder and coverage-sdk directory
- Add SDK_COVERAGE.md documentation for usage instructions

Author: ParidelPooya

packages/aws-durable-execution-sdk-js-examples/.gitignore

@@ -3,8 +3,10 @@
 /dist
 /dist-cjs
 /coverage
+/coverage-sdk
 *.iml
 .aws-sam/*
 *.zip
 
 src/utils/examples-catalog.json
+src/dur-sdk/

packages/aws-durable-execution-sdk-js-examples/SDK_COVERAGE.md

@@ -0,0 +1,49 @@
+# SDK Coverage in Examples Tests
+
+This package is configured to collect code coverage for the core SDK (`aws-durable-execution-sdk-js`) when running example tests.
+
+## How It Works
+
+1. **Pre-test Copy**: Before tests run, `scripts/copy-sdk-source.js` copies the SDK source files into `src/dur-sdk/`
+2. **Module Mapping**: Jest is configured to resolve `@aws/durable-execution-sdk-js` imports to the local `src/dur-sdk/index.ts`
+3. **Coverage Collection**: Jest collects coverage from both example files and SDK source files
+
+## Running Tests
+
+**Regular tests (examples only):**
+
+```bash
+npm test
+```
+
+**Tests with SDK coverage:**
+
+```bash
+npm run test-with-sdk-coverage
+```
+
+This will:
+
+- Copy SDK source to `src/dur-sdk/`
+- Run all example tests
+- Generate coverage report in `coverage-sdk/` directory
+
+## Coverage Output
+
+- **HTML Report**: `coverage-sdk/index.html`
+- **Cobertura XML**: `coverage-sdk/cobertura-coverage.xml`
+- **Console**: Summary printed after test run
+
+## Files
+
+- `scripts/copy-sdk-source.js` - Copies SDK source before tests
+- `jest.config.js` - Regular test configuration
+- `jest.config.sdk-coverage.js` - SDK coverage configuration
+- `src/dur-sdk/` - Temporary SDK source (gitignored)
+- `coverage-sdk/` - Coverage output directory (gitignored)
+
+## Notes
+
+- The `src/dur-sdk/` folder is automatically created and should not be committed
+- Coverage includes both example code and SDK code executed by the examples
+- The SDK source is copied fresh before each test run to ensure it's up-to-date

packages/aws-durable-execution-sdk-js-examples/jest.config.sdk-coverage.js

@@ -0,0 +1,20 @@
+const { createDefaultPreset } = require("ts-jest");
+
+const defaultPreset = createDefaultPreset();
+
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  ...defaultPreset,
+  testMatch: ["**/__tests__/**.test.ts", "**/src/examples/**/*.test.ts"],
+  coverageReporters: ["cobertura", "html", "text"],
+  coverageDirectory: "coverage-sdk",
+  collectCoverageFrom: [
+    "src/**/*.ts",
+    "!src/dur-sdk/run-durable.ts",
+    "!**/*.test.ts",
+    "!**/*.d.ts",
+  ],
+  moduleNameMapper: {
+    "^@aws/durable-execution-sdk-js$": "<rootDir>/src/dur-sdk/index.ts",
+  },
+};

packages/aws-durable-execution-sdk-js-examples/package.json

@@ -38,6 +38,9 @@
     "generate-template": "node scripts/generate-template.js",
     "test": "npm run unit-test",
     "test:integration": "NODE_ENV=integration jest --config jest.config.integration.js --testNamePattern=cloud",
+    "pretest-with-sdk-coverage": "node scripts/copy-sdk-source.js",
+    "test-with-sdk-coverage": "jest --config jest.config.sdk-coverage.js --collectCoverage",
+    "coverage-to-csv": "node scripts/coverage-to-csv.js",
     "unit-test": "jest --collectCoverage",
     "unit-test-watch": "jest --watch",
     "prettier": "prettier --write './src/**/*.*' && prettier --write './test/**/*.*'"

packages/aws-durable-execution-sdk-js-examples/scripts/copy-sdk-source.js

@@ -0,0 +1,16 @@
+const fs = require("fs");
+const path = require("path");
+
+const sdkSourcePath = path.resolve(
+  __dirname,
+  "../../aws-durable-execution-sdk-js/src",
+);
+const targetPath = path.resolve(__dirname, "../src/dur-sdk");
+
+if (fs.existsSync(targetPath)) {
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
+fs.cpSync(sdkSourcePath, targetPath, { recursive: true });
+
+console.log(`✓ Copied SDK source to ${targetPath}`);

packages/aws-durable-execution-sdk-js-examples/scripts/coverage-to-csv.js

@@ -0,0 +1,41 @@
+const fs = require("fs");
+const path = require("path");
+const xml2js = require("xml2js");
+
+const coverageFile = path.resolve(
+  __dirname,
+  "../coverage-sdk/cobertura-coverage.xml",
+);
+const outputFile = path.resolve(__dirname, "../coverage-sdk/coverage.csv");
+
+if (!fs.existsSync(coverageFile)) {
+  console.error(
+    "Coverage file not found. Run 'npm run test-with-sdk-coverage' first.",
+  );
+  process.exit(1);
+}
+
+const xml = fs.readFileSync(coverageFile, "utf8");
+
+xml2js.parseString(xml, (err, result) => {
+  if (err) {
+    console.error("Error parsing XML:", err);
+    process.exit(1);
+  }
+
+  const packages = result.coverage.packages[0].package;
+  const rows = [["File", "Line Coverage %"]];
+
+  packages.forEach((pkg) => {
+    pkg.classes[0].class.forEach((cls) => {
+      const filename = cls.$.filename;
+      const lineRate = (parseFloat(cls.$["line-rate"]) * 100).toFixed(2);
+      rows.push([filename, lineRate]);
+    });
+  });
+
+  const csv = rows.map((row) => row.join(",")).join("\n");
+  fs.writeFileSync(outputFile, csv);
+  console.log(`✓ Coverage CSV written to ${outputFile}`);
+  console.log(`  Total files: ${rows.length - 1}`);
+});