refactor: change convention for test file extension to opt-in to puyaTsTransformer

README.md

@@ -44,10 +44,14 @@ Let's write a simple contract and test it using the `algorand-typescript-testing
 
 #### Simulating AVM
 
-`algorand-typescript-testing` includes a TypeScript transformer (`puyaTsTransformer`) that ensures contracts (with `.algo.ts` extension) and tests (with `.spec.ts` or `.test.ts` extensions) behave consistently between Node.js and AVM environments.
+`algorand-typescript-testing` includes a TypeScript transformer (`puyaTsTransformer`) that ensures contracts (with `.algo.ts` extension) and tests (with `.algo.spec.ts` or `.algo.test.ts` extensions) behave consistently between Node.js and AVM environments.
 
 The transformer replicates AVM behavior, such as integer-only arithmetic where `3 / 2` produces `1`. For code requiring standard Node.js behaviour (e.g., `3 / 2` produces `1.5`), place it in separate `.ts` files and reference them from test files.
 
+The transformer also redirects `@algorandfoundation/algorand-typescript` imports to `@algorandfoundation/algorand-typescript-testing/internal` to provide executable implementations of Algorand TypeScript constructs like `Global`, `Box`, `Uint64`, and `clone`.
+
+If there are tests which do not need to be executed in the AVM context such as end to end tests, simply use `.test.ts` or `.spec.ts` file extensions without `.algo` part and the transformer would skip them.
+
 #### Configuring vitest
 
 If you are using [vitest](https://vitest.dev/) with [@rollup/plugin-typescript](https://www.npmjs.com/package/@rollup/plugin-typescript) plugin, configure `puyaTsTransformer` as a `before` stage transformer of the `typescript` plugin in `vitest.config.mts` file.
@@ -93,7 +97,7 @@ import { createDefaultEsmPreset, type JestConfigWithTsJest } from 'ts-jest'
 const presetConfig = createDefaultEsmPreset({})
 const jestConfig: JestConfigWithTsJest = {
   ...presetConfig,
-  testMatch: ['**/*.test.ts'],
+  testMatch: ['**/*.algo.test.ts'],
   setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
   transform: {
     '^.+\\.tsx?$': [

package.json

@@ -62,7 +62,7 @@
     "tsx": "4.19.3",
     "typedoc": "^0.28.1",
     "typedoc-plugin-markdown": "^4.6.0",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "upath": "^2.0.1",
     "vitest": "3.2.4"
   },

src/test-transformer/program-factory.ts

@@ -7,7 +7,7 @@ export interface TransformerConfig {
   testingPackageName: string
 }
 export const defaultTransformerConfig: TransformerConfig = {
-  includeExt: ['.algo.ts', '.spec.ts', '.test.ts'],
+  includeExt: ['.algo.ts', '.algo.spec.ts', '.algo.test.ts'],
   testingPackageName: '@algorandfoundation/algorand-typescript-testing',
 }
 

src/test-transformer/vitest-transformer.ts

@@ -28,7 +28,7 @@ programTransformer.factory = createProgramFactory(defaultTransformerConfig)
  ** @type {ts.TransformerFactory<ts.SourceFile> & ((config: Partial<TransformerConfig>) => ts.TransformerFactory<ts.SourceFile>)}
  *
  * @param {Partial<TransformerConfig>} [config] Configuration options
- * @param {string[]} [config.includeExt=['.algo.ts', '.spec.ts']] File extensions to process
+ * @param {string[]} [config.includeExt=['.algo.ts', '.algo.spec.ts']] File extensions to process
  * @param {string} [config.testingPackageName='@algorandfoundation/algorand-typescript-testing'] Package name for testing imports
  *
  * @example