Investigate vitest file imports

[Unshure]

Simplify Test Fixture Loading with Async fetch()

Overview

Update the loadFixture helper function to use the standard fetch() API, making it work consistently across both Node.js and browser test environments without requiring file system access or environment-specific implementations.

Current Implementation Problem

Today, test files use environment-specific implementations:

Node.js tests (tests_integ/__fixtures__/test-helpers.ts):

import { readFileSync } from 'node:fs'
import { join } from 'node:path'

export const loadFixture = (url: string): Uint8Array => {
  const relativePath = url.startsWith('/') ? url.slice(1) : url
  const filePath = join(process.cwd(), relativePath)
  return new Uint8Array(readFileSync(filePath))
}

Browser tests (tests_integ/browser/agent.browser.test.ts):

const loadFixture = async (url: string): Promise<Uint8Array> => {
  if (isNode) {
    // Node.js implementation with fs.readFileSync
  } else {
    // Browser implementation with fetch
    const response = await globalThis.fetch(url)
    const arrayBuffer = await response.arrayBuffer()
    return new Uint8Array(arrayBuffer)
  }
}

Issues:

• Requires different implementations for Node vs browser
• Node implementation uses fs.readFileSync (not available in browsers)
• Browser tests have duplicate loadFixture implementation with environment detection
• Synchronous in Node, async in browser (inconsistent API)

Desired Implementation

Based on Vite issue #12366, modern Node.js (20+) supports fetch() natively, allowing a single implementation:

Unified async helper:

export const loadFixture = async (url: string): Promise<Uint8Array> => {
  const arrayBuffer = await fetch(url).then(b => b.arrayBuffer())
  return new Uint8Array(arrayBuffer)
}

Usage:

import yellowPngUrl from './__resources__/yellow.png?url'
const imageBytes = await loadFixture(yellowPngUrl)

Implementation Requirements

1. Update loadFixture Helper

File: tests_integ/__fixtures__/test-helpers.ts

• Make function async returning Promise<Uint8Array>
• Replace fs.readFileSync with fetch(url).then(b => b.arrayBuffer())
• Remove fs and path imports
• Keep same signature: (url: string) => Promise<Uint8Array>

Before:

import { readFileSync } from 'node:fs'
import { join } from 'node:path'

export const loadFixture = (url: string): Uint8Array => {
  const relativePath = url.startsWith('/') ? url.slice(1) : url
  const filePath = join(process.cwd(), relativePath)
  return new Uint8Array(readFileSync(filePath))
}

After:

export const loadFixture = async (url: string): Promise<Uint8Array> => {
  const arrayBuffer = await fetch(url).then(b => b.arrayBuffer())
  return new Uint8Array(arrayBuffer)
}

2. Update Test Files to Use await

All test functions are already async, just need to add await when calling loadFixture:

Files to update:

• tests_integ/agent.test.ts
• tests_integ/bedrock.test.ts

Change:

// Before
const imageBytes = loadFixture(yellowPngUrl)

// After
const imageBytes = await loadFixture(yellowPngUrl)

3. Remove Duplicate Browser Implementation

File: tests_integ/browser/agent.browser.test.ts

• Remove the local loadFixture function (lines ~17-31)
• Import loadFixture from shared test helpers instead
• Update import statement:

  import { loadFixture } from '../__fixtures__/test-helpers.js'

4. Verification

Run tests in both environments to ensure no regressions:

# Node.js integration tests
npm run test:integ

# Browser integration tests  
npm run test:integ:browser

Verify:

• ✅ Tests pass in both Node and browser environments
• ✅ Image/PDF data loads correctly (yellow.png, letter.pdf)
• ✅ No performance degradation
• ✅ Unified implementation works across environments

Technical Details

Why This Works

• Node.js 20+: Native fetch() support (already required by project)
• Browser: fetch() is standard Web API
• Vite/Vitest: ?url imports work in both environments
  • Node: Returns file path that fetch() can load
  • Browser: Returns URL that fetch() can load

Benefits

✅ Single, unified implementation
✅ No environment detection needed
✅ No file system dependencies
✅ Works in Node, browser, and future environments
✅ Simpler codebase (removes ~15 lines of duplicate code)
✅ Consistent async API across all tests

Acceptance Criteria

• loadFixture updated in tests_integ/__fixtures__/test-helpers.ts
  • Function is async returning Promise<Uint8Array>
  • Uses fetch() instead of fs.readFileSync
  • No Node.js-specific imports (fs, path)
• Test files updated with await keyword
  • tests_integ/agent.test.ts
  • tests_integ/bedrock.test.ts
• Browser-specific implementation removed
  • Duplicate loadFixture removed from tests_integ/browser/agent.browser.test.ts
  • Import added from shared test helpers
• Tests pass in Node environment (npm run test:integ)
• Tests pass in browser environment (npm run test:integ:browser)
• Code quality checks pass (lint, format, type-check)
• No performance regressions

Files Affected

Modified:

• tests_integ/__fixtures__/test-helpers.ts (~5 lines changed)
• tests_integ/agent.test.ts (~2 lines changed, add await)
• tests_integ/bedrock.test.ts (~4 lines changed, add await)
• tests_integ/browser/agent.browser.test.ts (~15 lines removed, 1 import added)

Total: 4 files, approximately +5/-25 lines

Additional Context

This approach is based on the Vite maintainer's recommendation in issue #12366 and leverages Node.js 20's native fetch() support, which is already a project requirement (see package.json engines field).

Previous attempts to use a custom Vite plugin encountered technical blockers. This simpler solution achieves the same goal without additional dependencies or build configuration.

[zastrowm]

/strands investigate custom vite plugins or creating our own so that we don't have to manually read files and we could run these tests in the browser

[github-actions]

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and current file import patterns. Here's what I found:

Current Implementation

The project currently uses a two-step approach for loading test fixtures:

1. Import file path with ?url suffix: import yellowPngUrl from './__resources__/yellow.png?url'
2. Use helper function to load: const imageBytes = loadFixture(yellowPngUrl)

Problem: This approach requires different implementations for Node (using fs.readFileSync) vs browser (using fetch), limiting browser test compatibility.

Repository Context

• Test Framework: Vitest with 4 test projects (unit-node, unit-browser, integ-node, integ-browser)
• Browser Testing: Already configured with Playwright for Chromium
• Current Resources: Binary test files (yellow.png, letter.pdf) in tests_integ/__resources__/
• Affected Files: Multiple test files use the loadFixture pattern

---

Clarifying Questions

1. Plugin Implementation Strategy

Should we research and use an existing Vite plugin that supports importing files as bytes/binary data, or create a custom plugin from scratch?

• Existing plugin: Faster implementation, but may include extra features we don't need
• Custom plugin: Full control, but more implementation effort

2. Import Syntax

The issue suggests ?bytes. Should we use:

• ?bytes (implies returning Uint8Array)
• ?arraybuffer (returning ArrayBuffer)
• ?binary or another name?

3. Bundle Strategy

Should the plugin inline file contents into the bundle, or load them at runtime?

Option A - Inline embedding:

• ✅ Works in any environment (Node, browser, edge functions)
• ✅ No runtime file system access needed
• ❌ Larger bundle size

Option B - Runtime loading:

• ✅ Smaller bundle size
• ❌ Requires files to be available at runtime
• ❌ May not work in all deployment scenarios

For test files, Option A (inlining) seems preferable for browser compatibility. Thoughts?

4. Scope

Should this feature be available for:

• Test files only (tests_integ/**)?
• Both test and production code (src/**)?

5. File Type Support

Should this support:

• All file types?
• Only specific extensions (e.g., .png, .pdf, .jpg)?

Currently using: .png and .pdf files.

6. Migration Strategy

After implementing the plugin, should we:

• Migrate all existing test files to use the new syntax immediately?
• Keep both approaches and migrate gradually?
• Create an example but leave existing code as-is?

7. Helper Function

The current loadFixture helper function would become unnecessary. Should we:

• Remove it entirely and update all tests?
• Keep it for backward compatibility?

8. TypeScript Declarations

Where should type declarations for the new import syntax be placed?

• Create a new vite-env.d.ts file at project root?
• Add to existing types file?

Example declaration needed:

declare module '*.png?bytes' {
  const content: Uint8Array
  export default content
}

9. Documentation

Should we update these files with the new pattern?

• AGENTS.md (testing patterns section)
• CONTRIBUTING.md (if relevant for contributors)

10. Task Scope

This task potentially includes:

• Research/implementation of Vite plugin
• TypeScript type declarations
• Vitest configuration updates
• Test file migrations
• Documentation updates
• Verification in both Node and browser environments

Is this scope appropriate for a single PR, or should this be broken down into sub-tasks? For example:

• Task 1: Plugin implementation + TypeScript declarations + basic example
• Task 2: Migrate existing test files
• Task 3: Documentation updates

---

Please let me know your preferences on these points, and I'll update the issue with detailed implementation requirements.

[zastrowm]

/strands

Repository Analysis & Clarifying Questions

I've analyzed the repository structure and current file import patterns. Here's what I found:

Current Implementation

The project currently uses a two-step approach for loading test fixtures:

1. Import file path with ?url suffix: import yellowPngUrl from './__resources__/yellow.png?url'
2. Use helper function to load: const imageBytes = loadFixture(yellowPngUrl)

Problem: This approach requires different implementations for Node (using fs.readFileSync) vs browser (using fetch), limiting browser test compatibility.

Repository Context

• Test Framework: Vitest with 4 test projects (unit-node, unit-browser, integ-node, integ-browser)
• Browser Testing: Already configured with Playwright for Chromium
• Current Resources: Binary test files (yellow.png, letter.pdf) in tests_integ/__resources__/
• Affected Files: Multiple test files use the loadFixture pattern

Clarifying Questions

1. Plugin Implementation Strategy

Should we research and use an existing Vite plugin that supports importing files as bytes/binary data, or create a custom plugin from scratch?

• Existing plugin: Faster implementation, but may include extra features we don't need
• Custom plugin: Full control, but more implementation effort

Research what it would take with either

2. Import Syntax

The issue suggests ?bytes. Should we use:

• ?bytes (implies returning Uint8Array)
• ?arraybuffer (returning ArrayBuffer)
• ?binary or another name?

Choose the most general purpose

3. Bundle Strategy

Should the plugin inline file contents into the bundle, or load them at runtime?

Option A - Inline embedding:

• ✅ Works in any environment (Node, browser, edge functions)
• ✅ No runtime file system access needed
• ❌ Larger bundle size

Option B - Runtime loading:

• ✅ Smaller bundle size
• ❌ Requires files to be available at runtime
• ❌ May not work in all deployment scenarios

For test files, Option A (inlining) seems preferable for browser compatibility. Thoughts?

The purpose here is for integration tests (using vitest); so inline-embedding is fine. Furthermore, folks could always use await import if they wanted it deferred

4. Scope

Should this feature be available for:

• Test files only (tests_integ/**)?
• Both test and production code (src/**)?

Test files only

5. File Type Support

Should this support:

• All file types?
• Only specific extensions (e.g., .png, .pdf, .jpg)?

Any file type

Currently using: .png and .pdf files.

6. Migration Strategy

After implementing the plugin, should we:

• Migrate all existing test files to use the new syntax immediately?
• Keep both approaches and migrate gradually?
• Create an example but leave existing code as-is?

migrate all test files

7. Helper Function

The current loadFixture helper function would become unnecessary. Should we:

• Remove it entirely and update all tests?
• Keep it for backward compatibility?

8. TypeScript Declarations

Where should type declarations for the new import syntax be placed?

• Create a new vite-env.d.ts file at project root?
• Add to existing types file?

Example declaration needed:

declare module '*.png?bytes' {
const content: Uint8Array
export default content
}

Add a vite-env.d.ts that is used only for tests; nto src

9. Documentation

Should we update these files with the new pattern?

• AGENTS.md (testing patterns section)
• CONTRIBUTING.md (if relevant for contributors)

both but keep it concise

10. Task Scope

This task potentially includes:

• Research/implementation of Vite plugin
• TypeScript type declarations
• Vitest configuration updates
• Test file migrations
• Documentation updates
• Verification in both Node and browser environments

Is this scope appropriate for a single PR, or should this be broken down into sub-tasks? For example:

• Task 1: Plugin implementation + TypeScript declarations + basic example
• Task 2: Migrate existing test files
• Task 3: Documentation updates

Please let me know your preferences on these points, and I'll update the issue with detailed implementation requirements.

Keep it one self-contained task

[github-actions]

✅ Task Review Complete - Ready for Implementation

The issue has been refined and is ready for implementation.

What Was Accomplished

Repository Analysis:

• Analyzed current test file import patterns across Node and browser test environments
• Identified 4 test files using the loadFixture helper pattern
• Reviewed Vitest configuration with 4 test projects (unit-node, unit-browser, integ-node, integ-browser)
• Located test resources in tests_integ/__resources__/ (yellow.png, letter.pdf)

Clarifications Received:

• Plugin approach: Research both existing and custom options
• Import syntax: Choose most general-purpose option
• Bundle strategy: Inline embedding for tests
• Scope: Test files only, not production code
• File support: Any file type
• Migration: All test files to be migrated
• TypeScript: Create vite-env.d.ts for tests only
• Documentation: Update AGENTS.md and CONTRIBUTING.md (keep concise)
• Task scope: Single self-contained PR

Issue Updated With:

• Detailed implementation requirements across 6 phases
• Clear acceptance criteria
• List of affected files
• Technical constraints and considerations
• Examples of current vs. desired implementation

Implementation Scope

This task includes:

1. Research and implement/configure Vite plugin for binary imports
2. Create TypeScript declarations (vite-env.d.ts)
3. Migrate 4 test files to new import syntax
4. Remove loadFixture helper function
5. Verify in both Node and browser test environments
6. Update documentation (AGENTS.md, CONTRIBUTING.md)

Estimated Complexity: Medium
Files to Modify: ~6-8 files
New Files: 1 (vite-env.d.ts)

The task is well-scoped for a single developer to complete in approximately 2-4 days, including research, implementation, testing, and documentation.

[zastrowm]

/strands implement

[github-actions]

Implementation Progress Update

I've been working on implementing the Vite plugin for direct binary file imports. I've successfully:

✅ Created a custom Vite plugin structure in vitest.config.ts
✅ Added TypeScript declarations in vite-env.d.ts
✅ Migrated all test files to use the new ?arraybuffer import syntax
✅ Removed the loadFixture helper function

However, I've encountered a technical blocker:

Issue

The Vite plugin is not correctly intercepting the imports. The imported value is always a string (the file path) instead of a Uint8Array, regardless of the plugin configuration.

Debug output shows:

letterPdfBytes type: string  
letterPdfBytes is Uint8Array: false
letterPdfBytes[0]: / (the literal "/" character from the path)

I've tried multiple approaches:

• Using load hook
• Using transform hook
• Using resolveId + load with virtual modules
• Different query parameters (?bytes, ?arraybuffer)
• Path resolution with resolve() and dirname()
• Clearing Vite/Vitest caches

Question

Are there any existing examples of Vite plugins that successfully inline binary files as Uint8Arrays in the Vitest environment? Or is there a different approach I should consider for this use case?

The current implementation is on branch agent-tasks/225 if you'd like to review the plugin code.