influxdata
diff --git a/‎.github/workflows/test.yml‎
Lines changed: 699 additions & 0 deletions b/‎.github/workflows/test.yml‎
Lines changed: 699 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎.gitignore‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎DOCS-TESTING.md‎
Lines changed: 173 additions & 0 deletions b/‎DOCS-TESTING.md‎
Lines changed: 173 additions & 0 deletions
diff --git a/‎compose.yaml‎
Lines changed: 45 additions & 0 deletions b/‎compose.yaml‎
Lines changed: 45 additions & 0 deletions
diff --git a/‎package.json‎
Lines changed: 14 additions & 1 deletion b/‎package.json‎
Lines changed: 14 additions & 1 deletion
diff --git a/‎scripts/ci/detect-test-products.js‎
Lines changed: 101 additions & 0 deletions b/‎scripts/ci/detect-test-products.js‎
Lines changed: 101 additions & 0 deletions
@@ -45,6 +45,7 @@ test-results.xml
 /influxdb3cli-build-scripts/content
 tmp
 .tmp
+.test-cache
 
 # IDE files
 .vscode/*
 
@@ -124,6 +124,179 @@ Potential causes:
   # This is ignored
   ```
 
+### Performance Optimization
+
+Code block testing can be time-consuming for large documentation sets. Several optimization strategies are available:
+
+#### Parallel Test Execution by Language
+
+Test specific programming languages independently:
+
+```bash
+# Test only Python code blocks
+yarn test:codeblocks:python
+
+# Test only Bash/Shell code blocks
+yarn test:codeblocks:bash
+
+# Test only SQL code blocks
+yarn test:codeblocks:sql
+```
+
+**Benefits:**
+- Faster feedback for specific language changes
+- Easier debugging of language-specific issues
+- Enables parallel execution in CI
+
+#### Test Result Caching
+
+Cache successful test results to avoid retesting unchanged content:
+
+```bash
+# Inside test container
+./test/scripts/cached-test.sh content/influxdb/cloud/get-started/
+
+# View cache statistics
+yarn test:cache:stats
+
+# Clean expired cache entries
+yarn test:cache:clean
+```
+
+**How it works:**
+- Creates content hash for files/directories
+- Caches successful test results for 7 days
+- Skips tests if content unchanged and cache valid
+- Bypasses cache with `TEST_CACHE_BYPASS=1`
+
+#### Cache Management Commands
+
+```bash
+yarn test:cache:stats   # Show cache statistics
+yarn test:cache:list    # List all cached results
+yarn test:cache:clean   # Remove expired entries (>7 days)
+yarn test:cache:clear   # Remove all entries
+```
+
+#### Performance Comparison
+
+**Without optimization:** ~45 minutes (sequential)
+**With parallel execution:** ~18 minutes (59% faster)
+**With caching (2nd run):** ~5 seconds (97% faster)
+
+For comprehensive performance optimization documentation, see [test/TEST-PERFORMANCE.md](test/TEST-PERFORMANCE.md).
+
+### Code block testing in CI
+
+The `Test Code Blocks` GitHub Actions workflow
+(`.github/workflows/test.yml`) runs code block tests on demand. Pull
+requests trigger a detection-only pass that suggests which products
+to test; actual test execution runs via `workflow_dispatch`.
+
+**On pull requests:**
+
+- Detects changed content and test-harness files (`content/**/*.md`,
+  `test/**`, `Dockerfile.pytest`, `compose.yaml`)
+- Resolves shared content changes to the consuming products
+- Posts a summary with suggested products, partitioned into
+  "runnable" (products with a pytest service in `compose.yaml`) and
+  "not yet runnable"
+- Does not run tests or block the PR
+
+**Manual runs (`workflow_dispatch`):**
+
+- Trigger from the Actions UI or with `gh workflow run`:
+  ```bash
+  gh workflow run "Test Code Blocks" \
+    --repo influxdata/docs-v2 \
+    -f products=core,telegraf \
+    -f use_default_group=false
+  ```
+- The default group is `influxdb3_core` and `telegraf`
+- Content failures surface as `::warning::` annotations and in the
+  job summary; they do not fail the matrix job
+
+**Products that run against a live server in CI:**
+
+| Product | Status | How |
+| --- | --- | --- |
+| `influxdb3_core` | Runs live | Started via `docker compose up influxdb3-core` with a preconfigured offline admin token generated at job start |
+| `influxdb3_enterprise` | Gated on license blob | Requires `INFLUXDB3_ENTERPRISE_LICENSE_BLOB` repo secret (see below). When unset, Enterprise is skipped with an informational notice |
+| `telegraf`, `v2`, `cloud`, `cloud-dedicated`, `cloud-serverless`, `clustered` | Mock credentials | Tests that hit real endpoints may fail; content-only checks still run |
+
+### Provision InfluxDB 3 Enterprise for CI
+
+Enterprise trial-license activation requires email verification, which
+can't complete in a headless CI environment. CI therefore expects a
+pre-activated license blob stored as a repository secret. Produce it
+once locally, then upload.
+
+**1. Register the verification email.**
+
+Choose an email address you control and have InfluxData approve it for
+trial licensing. The email is stored in the repo secret
+`INFLUXDB3_ENTERPRISE_LICENSE_EMAIL`.
+
+**2. Activate Enterprise locally with that email.**
+
+```bash
+# Create the directory Docker Compose expects
+mkdir -p ~/influxdata-docs/.influxdb3/enterprise/data
+
+# Point compose at the verified email
+echo "INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=<verified-email>" \
+  > ~/influxdata-docs/.influxdb3/enterprise/.env
+
+# Generate an admin token file (compose mounts it as a secret)
+TOKEN="apiv3_$(openssl rand -hex 32)"
+cat > ~/influxdata-docs/.influxdb3/enterprise/admin-token.json <<EOF
+{"token":"${TOKEN}","name":"_admin","description":"Local admin token"}
+EOF
+chmod 0600 ~/influxdata-docs/.influxdb3/enterprise/admin-token.json
+
+# Start Enterprise. Watch the logs until activation completes.
+docker compose --profile shared up -d influxdb3-enterprise
+docker compose logs -f influxdb3-enterprise
+```
+
+The first activation with a pre-approved email should skip the
+"Waiting for verification..." stall and persist a license file at
+`~/influxdata-docs/.influxdb3/enterprise/data/cluster0/trial_or_home_license`.
+After you see activation succeed, stop the server:
+
+```bash
+docker compose --profile shared down
+```
+
+**3. Upload the license blob as a repo secret.**
+
+```bash
+LICENSE=~/influxdata-docs/.influxdb3/enterprise/data/cluster0/trial_or_home_license
+base64 -i "$LICENSE" | gh secret set INFLUXDB3_ENTERPRISE_LICENSE_BLOB \
+  --repo influxdata/docs-v2
+```
+
+**4. Verify CI picks it up.**
+
+```bash
+gh workflow run "Test Code Blocks" \
+  --repo influxdata/docs-v2 \
+  -f products=enterprise \
+  -f use_default_group=false
+```
+
+The Enterprise job should now decode the blob into
+`/var/lib/influxdb3/data/cluster0/trial_or_home_license`, start the
+server, and run pytest against it.
+
+> \[!Note]
+> #### License expiration
+>
+> Trial licenses have a finite validity window. When the license
+> encoded in `INFLUXDB3_ENTERPRISE_LICENSE_BLOB` expires, Enterprise
+> CI jobs will fail to start. Re-run the activation locally and
+> upload a fresh blob.
+
 ## LLM-Friendly Markdown Generation
 
 The documentation includes tooling to generate LLM-friendly Markdown versions of documentation pages, both locally via CLI and on-demand via Lambda\@Edge in production.
 
@@ -304,6 +304,49 @@ services:
         source: test-content
         target: /app/content
     working_dir: /app
+  influxdb3-enterprise-pytest:
+    container_name: influxdb3-enterprise-pytest
+    image: influxdata/docs-pytest
+    build:
+      context: .
+      dockerfile: Dockerfile.pytest
+    entrypoint:
+      - /bin/bash
+      - /src/test/scripts/run-tests.sh
+      - pytest
+    command:
+      - content/influxdb3/enterprise/**/*.md
+      - content/shared/**/*.md
+    environment:
+      - CONTENT_PATH=content/influxdb3/enterprise
+    profiles:
+      - test
+      - influxdb3
+    stdin_open: true
+    tty: true
+    volumes:
+      - type: bind
+        source: .
+        target: /src
+        read_only: true
+      - type: bind
+        source: ./test/shared
+        target: /shared
+      - type: bind
+        source: ./content/influxdb3/enterprise/.env.test
+        target: /app/.env.test
+        read_only: true
+      - type: bind
+        source: ./static/downloads
+        target: /app/data
+        read_only: true
+      - type: volume
+        source: influxdb3-enterprise-tmp
+        target: /app/iot-starter
+      - type: volume
+        source: test-content
+        target: /app/content
+    working_dir: /app
   # ============================================================================
   # InfluxDB 3 Core - PER-WORKTREE INSTANCE
   # ============================================================================
@@ -625,6 +668,8 @@ services:
         read_only: false
 volumes:
   test-content:
+  influxdb3-core-tmp:
+  influxdb3-enterprise-tmp:
   cloud-tmp:
   cloud-dedicated-tmp:
   cloud-serverless-tmp:
 
@@ -85,15 +85,28 @@
     "lint": "LEFTHOOK_EXCLUDE=test lefthook run pre-commit && lefthook run pre-push",
     "pre-commit": "lefthook run pre-commit",
     "test": "echo \"Run 'yarn test:e2e', 'yarn test:links', 'yarn test:codeblocks:all' or a specific test command. e2e and links test commands can take a glob of file paths to test. Some commands run automatically during the git pre-commit and pre-push hooks.\" && exit 0",
-    "test:codeblocks": "echo \"Run a specific codeblocks test command\" && exit 0",
+    "test:codeblocks": "echo \"Run a specific codeblocks test command (e.g., yarn test:codeblocks:influxdb3_core)\" && exit 0",
     "test:codeblocks:all": "docker compose --profile test up",
+    "test:codeblocks:default": "yarn test:codeblocks:influxdb3_core & P1=$! ; yarn test:codeblocks:telegraf & P2=$! ; wait $P1 ; E1=$? ; wait $P2 ; E2=$? ; exit $((E1 | E2))",
+    "test:codeblocks:parallel": "docker compose run --rm cloud-pytest & docker compose run --rm v2-pytest & docker compose run --rm telegraf-pytest & wait",
+    "test:codeblocks:influxdb3_core": "docker compose run --rm --name influxdb3-core-pytest influxdb3-core-pytest",
+    "test:codeblocks:influxdb3_enterprise": "docker compose run --rm --name influxdb3-enterprise-pytest influxdb3-enterprise-pytest",
     "test:codeblocks:cloud": "docker compose run --rm --name cloud-pytest cloud-pytest",
     "test:codeblocks:cloud-dedicated": "./test/scripts/monitor-tests.sh start cloud-dedicated-pytest && docker compose run --name cloud-dedicated-pytest cloud-dedicated-pytest",
     "test:codeblocks:cloud-serverless": "docker compose run --rm --name cloud-serverless-pytest cloud-serverless-pytest",
     "test:codeblocks:clustered": "./test/scripts/monitor-tests.sh start clustered-pytest && docker compose run --name clustered-pytest clustered-pytest",
+    "test:codeblocks:explorer": "echo '⚠️ InfluxDB 3 Explorer pytest service not yet configured. Add explorer-pytest to compose.yaml.' && exit 0",
     "test:codeblocks:telegraf": "docker compose run --rm --name telegraf-pytest telegraf-pytest",
+    "test:codeblocks:v1": "echo '⚠️ InfluxDB v1 pytest service not yet configured. Add v1-pytest to compose.yaml.' && exit 0",
     "test:codeblocks:v2": "docker compose run --rm --name v2-pytest v2-pytest",
     "test:codeblocks:stop-monitors": "./test/scripts/monitor-tests.sh stop cloud-dedicated-pytest && ./test/scripts/monitor-tests.sh stop clustered-pytest",
+    "test:codeblocks:python": "echo 'Testing Python code blocks...' && docker compose run --rm cloud-pytest bash -c './test/scripts/test-by-language.sh python content/influxdb/cloud/**/*.md'",
+    "test:codeblocks:bash": "echo 'Testing Bash/Shell code blocks...' && docker compose run --rm cloud-pytest bash -c './test/scripts/test-by-language.sh bash content/influxdb/cloud/**/*.md'",
+    "test:codeblocks:sql": "echo 'Testing SQL code blocks...' && docker compose run --rm cloud-pytest bash -c './test/scripts/test-by-language.sh sql content/influxdb/cloud/**/*.md'",
+    "test:cache:stats": "./test/scripts/manage-test-cache.sh stats",
+    "test:cache:clean": "./test/scripts/manage-test-cache.sh clean",
+    "test:cache:clear": "./test/scripts/manage-test-cache.sh clear",
+    "test:cache:list": "./test/scripts/manage-test-cache.sh list",
     "test:e2e": "node cypress/support/run-e2e-specs.js",
     "test:render-regression": "node cypress/support/run-e2e-specs.js --spec \"cypress/e2e/content/render-regression.cy.js\" --no-mapping",
     "test:render-artifacts": ".ci/scripts/check-render-artifacts.sh public",
 
@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Detect which products need testing based on changed content files.
+ *
+ * Usage:
+ *   echo "content/influxdb3/core/page.md" | node scripts/ci/detect-test-products.js
+ *   node scripts/ci/detect-test-products.js < changed-files.txt
+ *
+ * Output (JSON):
+ *   {"products":["influxdb3_core","telegraf"],"files":["content/influxdb3/core/page.md",...]}
+ *
+ * This script:
+ * 1. Reads changed file paths from stdin (one per line)
+ * 2. Expands shared content changes to find all affected product pages
+ * 3. Extracts unique products from the affected file paths
+ * 4. Outputs JSON with products array and expanded files array
+ */
+
+import { expandSharedContentChanges } from '../lib/content-utils.js';
+
+// Product path mappings
+const PRODUCT_PATTERNS = [
+  { pattern: /^content\/influxdb3\/core\//, product: 'influxdb3_core' },
+  { pattern: /^content\/influxdb3\/enterprise\//, product: 'influxdb3_enterprise' },
+  { pattern: /^content\/influxdb3\/cloud-dedicated\//, product: 'cloud-dedicated' },
+  { pattern: /^content\/influxdb3\/cloud-serverless\//, product: 'cloud-serverless' },
+  { pattern: /^content\/influxdb3\/clustered\//, product: 'clustered' },
+  { pattern: /^content\/influxdb3\/explorer\//, product: 'explorer' },
+  { pattern: /^content\/influxdb\/cloud\//, product: 'cloud' },
+  { pattern: /^content\/influxdb\/v2\//, product: 'v2' },
+  { pattern: /^content\/influxdb\/v1\//, product: 'v1' },
+  { pattern: /^content\/telegraf\//, product: 'telegraf' },
+];
+
+/**
+ * Extract product identifier from a content file path
+ * @param {string} filePath - Content file path
+ * @returns {string|null} Product identifier or null
+ */
+function getProductFromPath(filePath) {
+  for (const { pattern, product } of PRODUCT_PATTERNS) {
+    if (pattern.test(filePath)) {
+      return product;
+    }
+  }
+  return null;
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  // Read changed files from stdin
+  const input = await new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+
+    // Handle case where stdin is empty/closed immediately
+    if (process.stdin.isTTY) {
+      resolve('');
+    }
+  });
+
+  const changedFiles = input
+    .trim()
+    .split('\n')
+    .filter((f) => f && f.endsWith('.md'));
+
+  if (changedFiles.length === 0) {
+    console.log(JSON.stringify({ products: [], files: [] }));
+    process.exit(0);
+  }
+
+  // Expand shared content changes to find all affected pages
+  const verbose = process.env.VERBOSE === 'true';
+  const expandedFiles = expandSharedContentChanges(changedFiles, { verbose });
+
+  // Extract unique products from expanded file list
+  const products = new Set();
+  for (const file of expandedFiles) {
+    const product = getProductFromPath(file);
+    if (product) {
+      products.add(product);
+    }
+  }
+
+  // Output JSON result
+  const result = {
+    products: Array.from(products).sort(),
+    files: expandedFiles.sort(),
+  };
+
+  console.log(JSON.stringify(result));
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});