feat: implement automatic test file detection and allow unrestricted imports for test files

Author: andrewmolyuk

README.md

@@ -14,6 +14,7 @@ A custom ESLint plugin for enforcing modular patterns in Vue 3 projects.
 - Custom linting rules for Vue 3 modular architecture
 - Supports single-file components (SFC)
 - Enforces architectural boundaries between features
+- **Automatic test file detection** - test files can import from anywhere without restrictions
 - Supports both flat config (ESLint v9+) and legacy config formats
 - Easily extendable for your team's needs
 

docs/rules/enforce-import-boundaries.md

@@ -75,4 +75,9 @@ Use the `allow` option to whitelist specific import patterns when necessary. The
 
 - The rule ignores imports not starting with the configured `src` root, relative imports are resolved against the importer file.
 - Type-only imports can be ignored by setting `ignoreTypeImports: true` (default).
-- Test files may require special allowances. Use the `allow` option to whitelist `tests/**` or add ESLint override sections for test directories.
+- Test files are automatically detected and allowed to import from anywhere without restrictions. This includes:
+  - Files in `tests/` directories (e.g., `tests/unit/auth.test.js`, `/project/tests/integration/`)
+  - Files with `.test.` in the name (e.g., `component.test.js`, `utils.test.ts`)
+  - Files with `.spec.` in the name (e.g., `component.spec.js`, `utils.spec.ts`)
+  - Files in `__tests__/` directories (e.g., `src/__tests__/setup.js`, `src/components/__tests__/Button.js`)
+- For additional custom patterns, use the `allow` option to whitelist specific import patterns or add ESLint override sections for custom test directories.

docs/vue3-project-modules-blueprint.md

@@ -217,29 +217,25 @@ export type { SearchResult, SearchFilters } from './entities/SearchResult'
 
 ## Testing and test folder exceptions
 
-Tests often need deeper access to implementation details. Test code (placed under `tests/`, `__tests__/` or similar) is allowed to import from any layer — including internal module files — to make unit and integration testing practical.
+Tests often need deeper access to implementation details. Test code is automatically allowed to import from any layer — including internal module files — to make unit and integration testing practical.
 
-This allowance also applies to individual test files following common naming patterns such as `*.test.*` or `*.spec.*` (for example: `some.test.ts`, `some.spec.ts`, `some.test.tsx`).
+**Automatic Test File Detection**: The ESLint rules automatically detect test files and allow them unrestricted imports. This includes:
+
+- Files in `tests/` directories (e.g., `tests/unit/auth.test.js`, `/project/tests/integration/`)
+- Files with `.test.` in the name (e.g., `component.test.js`, `utils.test.ts`)
+- Files with `.spec.` in the name (e.g., `component.spec.js`, `utils.spec.ts`)
+- Files in `__tests__/` directories (e.g., `src/__tests__/setup.js`, `src/components/__tests__/Button.js`)
+
+**No additional configuration required** - test files are detected automatically and exempt from import boundary restrictions.
 
 Recommended patterns:
 
 - Unit tests: importing internal files directly is acceptable to test implementation specifics.
 - Integration tests: prefer exercising modules/features through their public API (`index.ts`) to validate real integration points.
 - Test helpers: create a `tests/test-utils.ts` or `tests/utils/` that re-exports common setup/mocks; prefer adapters that call public APIs when feasible to ease refactors.
 - Organization: keep internal-focused tests separate (e.g. `tests/internal/`) from cross-module/integration tests.
-- Tooling: configure ESLint rules to allow `tests/**` exceptions (for example, whitelist `tests/**` in the `no-cross-module-imports` rule) so test imports do not trigger violations.
-
-Example ESLint whitelist pattern (conceptual):
-
-`allowedPatterns: ['tests/**', '**/*.spec.{js,ts,tsx}', '**/*.test.{js,ts,tsx}']`
-
-Note: if your tests are located outside `src/` (for example a top-level `tests/` folder), some ESLint configurations or path-based rule implementations that only scan `src/**` may ignore them. To ensure test files are checked:
-
-- Add the test paths to your ESLint file globs or the rule's whitelist (as shown above).
-- Use an `.eslintrc` `overrides` section to enable rules for `**/*.spec.*` / `**/*.test.*` and `tests/**` paths.
-- Or place tests under `src/` so they fall under existing `src/**` globs.
 
-These options make sure test-only imports are permitted for testing purposes while keeping runtime import rules enforced for production code.
+For custom test patterns not covered by automatic detection, you can still use the `allow` option in ESLint rule configurations to whitelist specific patterns.
 
 Keep test-only imports clearly flagged as test code and out of production bundles (tests should not accidentally ship in the app). These exceptions exist to improve testability without weakening runtime architectural guarantees.
 

src/index.js

@@ -9,6 +9,9 @@ import enforceFeatureExports from './rules/enforce-feature-exports.js'
 import enforceImportBoundaries from './rules/enforce-import-boundaries.js'
 import enforceNamingConvention from './rules/enforce-naming-convention.js'
 
+// Import utilities
+import { isTestFile } from './utils/import-boundaries.js'
+
 const plugin = {
   meta,
   rules: {
@@ -23,6 +26,9 @@ const plugin = {
   },
   processors: {},
   configs: {},
+  utils: {
+    isTestFile,
+  },
 }
 
 // Flat config for ESLint v9+

src/rules/enforce-import-boundaries.js

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { isTestFile } from '../utils/import-boundaries.js'
 
 const defaultOptions = {
   src: 'src',
@@ -20,6 +21,12 @@ function resolveAlias(importPath, aliases) {
 
 function getLayerForFile(filePath, options) {
   if (!filePath) return null
+
+  // Check if this is a test file first
+  if (isTestFile(filePath)) {
+    return { layer: 'test' }
+  }
+
   const parts = path.normalize(filePath).split(path.sep)
   const srcIdx = parts.indexOf(options.src)
   if (srcIdx === -1) return null
@@ -110,6 +117,9 @@ export default {
       const importerFilename = context.getFilename()
       if (!importerFilename || importerFilename === '<input>') return
 
+      // Allow test files to import from anywhere without restrictions
+      if (isTestFile(importerFilename)) return
+
       let resolved = resolveAlias(importPathRaw, opts.aliases)
       // support common @/ alias mapping to src when not configured
       if (resolved.startsWith('@/')) {

src/rules/no-cross-feature-imports.js

@@ -1,4 +1,4 @@
-import { isDeepFeatureImport, getModulePublicImport, isWithinSameFeature } from '../utils/import-boundaries.js'
+import { isDeepFeatureImport, getModulePublicImport, isWithinSameFeature, isTestFile } from '../utils/import-boundaries.js'
 
 export default {
   meta: {
@@ -51,6 +51,9 @@ export default {
       ImportDeclaration(node) {
         const source = node.source.value
 
+        // Allow test files to import from anywhere without restrictions
+        if (isTestFile(filename)) return
+
         const modulePublicName = getModulePublicImport(source, opts)
         if (modulePublicName) {
           const isAppLayerFile = filename.includes(`/${src}/app/`)

src/rules/no-cross-module-imports.js

@@ -1,4 +1,4 @@
-import { isDeepModuleImport, isWithinSameModule, applyAliases } from '../utils/import-boundaries.js'
+import { isDeepModuleImport, isWithinSameModule, applyAliases, isTestFile } from '../utils/import-boundaries.js'
 
 export default {
   meta: {
@@ -46,6 +46,9 @@ export default {
         const source = node.source.value
         if (!source.includes('/')) return
 
+        // Allow test files to import from anywhere without restrictions
+        if (isTestFile(filename)) return
+
         // normalize input to helper expectations
         const opts = { src, modulesDir }
         const aliased = applyAliases(source, options.aliases || {}, opts.src)

src/utils/import-boundaries.js

@@ -7,6 +7,35 @@ export const defaultOptions = {
   aliases: {},
 }
 
+/**
+ * Check if a file is a test file based on common patterns
+ * @param {string} filePath - Path to the file
+ * @returns {boolean} - True if the file is a test file
+ */
+export function isTestFile(filePath) {
+  if (!filePath) return false
+
+  const normalizedPath = path.normalize(filePath)
+  const basename = path.basename(filePath)
+
+  // Check if file is in a tests directory (sibling to src or anywhere in the path)
+  if (normalizedPath.includes('/tests/') || normalizedPath.includes('\\tests\\')) {
+    return true
+  }
+
+  // Check if file has test patterns in the name
+  if (basename.includes('.test.') || basename.includes('.spec.')) {
+    return true
+  }
+
+  // Check for __tests__ directories (common Jest pattern)
+  if (normalizedPath.includes('/__tests__/') || normalizedPath.includes('\\__tests__\\')) {
+    return true
+  }
+
+  return false
+}
+
 export function applyAliases(importPath, aliases, defaultSrc) {
   for (const [k, v] of Object.entries(aliases || {})) {
     if (importPath === k || importPath.startsWith(k + '/')) {

tests/test-files-handling.spec.js

@@ -0,0 +1,147 @@
+import { describe, it, beforeEach, expect } from 'vitest'
+import { RuleTester } from 'eslint'
+import plugin from '../src/index.js'
+
+describe('Test files handling', () => {
+  let ruleTester
+
+  beforeEach(() => {
+    ruleTester = new RuleTester({
+      languageOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+      },
+      plugins: {
+        'vue-modular': plugin,
+      },
+    })
+
+    if (global.__eslintVueModularState) delete global.__eslintVueModularState
+  })
+
+  describe('enforce-import-boundaries', () => {
+    it('should allow test files to import from anywhere', () => {
+      ruleTester.run('enforce-import-boundaries', plugin.rules['enforce-import-boundaries'], {
+        valid: [
+          // ✅ Test files in tests/ directory can import module internals
+          {
+            code: "import userService from '@/modules/user/services/userService'",
+            filename: '/project/tests/user.test.js',
+          },
+          {
+            code: "import { UserComponent } from '@/modules/user/components/UserProfile'",
+            filename: '/project/tests/unit/user-module.spec.js',
+          },
+          // ✅ Test files with .test. pattern can import feature internals
+          {
+            code: "import loginValidator from '@/features/auth/validators/loginValidator'",
+            filename: '/project/src/features/auth/login.test.js',
+          },
+          {
+            code: "import { searchHelpers } from '@/features/search/utils/helpers'",
+            filename: '/project/src/utils/search.spec.ts',
+          },
+          // ✅ Test files with .spec. pattern can import app internals
+          {
+            code: "import appConfig from '@/app/config/settings'",
+            filename: '/project/src/app/app.spec.js',
+          },
+          // ✅ Test files in __tests__ directory can import anything
+          {
+            code: "import { StoreModule } from '@/stores/user'",
+            filename: '/project/src/modules/auth/__tests__/auth-store.test.js',
+          },
+          {
+            code: "import componentHelpers from '@/components/Button/helpers'",
+            filename: '/project/src/__tests__/components.spec.js',
+          },
+          // ✅ Top-level tests folder (sibling to src) can import anything
+          {
+            code: "import { getAllModules } from '@/modules/admin/internal/utils'",
+            filename: '/project/tests/integration/admin.test.js',
+          },
+        ],
+        invalid: [],
+      })
+    })
+  })
+
+  describe('no-cross-module-imports', () => {
+    it('should allow test files to import across modules', () => {
+      ruleTester.run('no-cross-module-imports', plugin.rules['no-cross-module-imports'], {
+        valid: [
+          // ✅ Test files can import deep into other modules
+          {
+            code: "import userService from '@/modules/user/services/userService'",
+            filename: '/project/tests/admin.test.js',
+          },
+          {
+            code: "import { AdminComponent } from '../../modules/admin/components/AdminPanel'",
+            filename: '/project/src/modules/user/user.spec.js',
+          },
+          // ✅ Files with test patterns can cross module boundaries
+          {
+            code: "import billingUtils from '@/modules/billing/utils/calculator'",
+            filename: '/project/src/modules/user/billing.test.ts',
+          },
+        ],
+        invalid: [],
+      })
+    })
+  })
+
+  describe('no-cross-feature-imports', () => {
+    it('should allow test files to import across features', () => {
+      ruleTester.run('no-cross-feature-imports', plugin.rules['no-cross-feature-imports'], {
+        valid: [
+          // ✅ Test files can import deep into other features
+          {
+            code: "import authValidator from '@/features/auth/validators/loginValidator'",
+            filename: '/project/tests/search.test.js',
+          },
+          {
+            code: "import { SearchComponent } from '../../features/search/components/SearchBar'",
+            filename: '/project/src/features/auth/auth.spec.js',
+          },
+          // ✅ Files with test patterns can cross feature boundaries
+          {
+            code: "import notificationHelpers from '@/features/notifications/utils/helpers'",
+            filename: '/project/src/features/user/notifications.test.ts',
+          },
+        ],
+        invalid: [],
+      })
+    })
+  })
+
+  describe('isTestFile utility', () => {
+    it('should correctly identify test files', () => {
+      const { isTestFile } = plugin.utils || {}
+
+      if (isTestFile) {
+        // Files in tests/ directory
+        expect(isTestFile('/project/tests/user.js')).toBe(true)
+        expect(isTestFile('/project/tests/unit/auth.js')).toBe(true)
+        expect(isTestFile('/project/src/tests/helpers.js')).toBe(true)
+
+        // Files with .test. pattern
+        expect(isTestFile('/project/src/components/Button.test.js')).toBe(true)
+        expect(isTestFile('/project/src/utils/helpers.test.ts')).toBe(true)
+
+        // Files with .spec. pattern
+        expect(isTestFile('/project/src/components/Button.spec.js')).toBe(true)
+        expect(isTestFile('/project/src/utils/helpers.spec.ts')).toBe(true)
+
+        // Files in __tests__ directory
+        expect(isTestFile('/project/src/__tests__/setup.js')).toBe(true)
+        expect(isTestFile('/project/src/components/__tests__/Button.js')).toBe(true)
+
+        // Non-test files
+        expect(isTestFile('/project/src/components/Button.js')).toBe(false)
+        expect(isTestFile('/project/src/utils/helpers.js')).toBe(false)
+        expect(isTestFile('/project/src/stores/user.js')).toBe(false)
+        expect(isTestFile('/project/src/modules/auth/index.js')).toBe(false)
+      }
+    })
+  })
+})