Deprecate old testing framework in favor of createTester

.chronus/changes/deprecate-old-testing-framework-2026-6-11.md

@@ -0,0 +1,23 @@
+---
+changeKind: deprecation
+packages:
+  - "@typespec/compiler"
+  - "@typespec/http"
+  - "@typespec/rest"
+  - "@typespec/versioning"
+  - "@typespec/json-schema"
+  - "@typespec/xml"
+  - "@typespec/events"
+  - "@typespec/sse"
+  - "@typespec/streams"
+  - "@typespec/html-program-viewer"
+  - "@typespec/library-linter"
+  - "@typespec/emitter-framework"
+  - "@typespec/http-client-js"
+  - "@typespec/http-client"
+  - "@typespec/http-server-js"
+  - "@typespec/openapi"
+  - "@typespec/openapi3"
+---
+
+Deprecate old testing framework (`createTestHost`, `createTestRunner`, `createTestWrapper`, `createTestLibrary`, `BasicTestRunner`, `TypeSpecTestLibrary`, etc.). Use `createTester` from `@typespec/compiler/testing` instead.

packages/compiler/src/testing/code-fix-testing.ts

@@ -48,6 +48,7 @@ export function expectCodeFixOnAst(code: string, callback: (node: Node) => CodeF
     const node = getNodeAtPosition(script, pos);
     ok(node, "Expected node at cursor. Make sure to have ┆ to mark which node.");
     const codefix = callback(node);
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     const host = await createTestHost();
     let updatedContent: string | undefined;
     await applyCodeFix(
@@ -90,6 +91,7 @@ export function expectCodeFixesOnAst(
     }
     ok(diagnostics.length > 0, "Expected node at cursor. Make sure to have ┆ to mark which node.");
     const codeFixes = callback(diagnostics);
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     const host = await createTestHost();
     let updatedContent: string | undefined;
     await applyCodeFixes(

packages/compiler/src/testing/fs.ts

@@ -123,6 +123,7 @@ function createTestFileSystemInternal(
     jsImports.set(key, exports);
   }
 
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
   async function addTypeSpecLibrary(testLibrary: TypeSpecTestLibrary) {
     assertNotFrozen();
 

packages/compiler/src/testing/index.ts

@@ -15,6 +15,7 @@ export {
 } from "./rule-tester.js";
 export { extractCursor, extractSquiggles } from "./source-utils.js";
 export type { TestHostOptions } from "./test-compiler-host.js";
+/* eslint-disable @typescript-eslint/no-deprecated -- exporting deprecated APIs for backward compatibility */
 export { createTestHost, createTestRunner, findFilesFromPattern } from "./test-host.js";
 export {
   createTestLibrary,
@@ -25,9 +26,9 @@ export {
   trimBlankLines,
   type TestWrapperOptions,
 } from "./test-utils.js";
+/* eslint-enable @typescript-eslint/no-deprecated */
 export { createTester } from "./tester.js";
 export type {
-  BasicTestRunner,
   EmitterTester,
   EmitterTesterInstance,
   JsFile,
@@ -36,12 +37,17 @@ export type {
   TestCompileResult,
   TestEmitterCompileResult,
   TestFileSystem as TestFileSystem,
+  Tester,
+  TesterInstance,
+} from "./types.js";
+/* eslint-disable @typescript-eslint/no-deprecated -- exporting deprecated APIs for backward compatibility */
+export type {
+  BasicTestRunner,
   TestFiles,
   TestHost,
   TestHostConfig,
   TestHostError,
-  Tester,
-  TesterInstance,
   TypeSpecTestLibrary,
   TypeSpecTestLibraryInit,
 } from "./types.js";
+/* eslint-enable @typescript-eslint/no-deprecated */

packages/compiler/src/testing/rule-tester.ts

@@ -69,6 +69,7 @@ export interface ApplyCodeFixExpect {
 }
 
 export function createLinterRuleTester(
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
   runner: BasicTestRunner | TesterInstance,
   ruleDef: LinterRuleDefinition<string, DiagnosticMessages>,
   libraryName: string,
@@ -221,6 +222,7 @@ export function createLinterRuleTester(
   }
 }
 
+// eslint-disable-next-line @typescript-eslint/no-deprecated
 function isLegacyTestRunner(tester: BasicTestRunner | TesterInstance): tester is BasicTestRunner {
   return "autoCodeOffset" in tester;
 }

packages/compiler/src/testing/test-compiler-host.ts

@@ -6,6 +6,7 @@ import { CompilerHost, StringLiteral, Type } from "../core/types.js";
 import { resolveVirtualPath } from "./fs.js";
 import { TestFileSystem, TestHostError, TypeSpecTestLibrary } from "./types.js";
 
+// eslint-disable-next-line @typescript-eslint/no-deprecated
 export const StandardTestLibrary: TypeSpecTestLibrary = {
   name: "@typespec/compiler",
   packageRoot: CompilerPackageRoot,
@@ -44,6 +45,7 @@ export function createTestCompilerHost(
     async readUrl(url: string) {
       const contents = virtualFs.get(url);
       if (contents === undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         throw new TestHostError(`File ${url} not found.`, "ENOENT");
       }
       return createSourceFile(contents, url);
@@ -52,6 +54,7 @@ export function createTestCompilerHost(
       path = resolveVirtualPath(path);
       const contents = virtualFs.get(path);
       if (contents === undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         throw new TestHostError(`File ${path} not found.`, "ENOENT");
       }
       return createSourceFile(contents, path);
@@ -100,6 +103,7 @@ export function createTestCompilerHost(
       path = resolveVirtualPath(path);
       const module = jsImports.get(path);
       if (module === undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         throw new TestHostError(`Module ${path} not found`, "ERR_MODULE_NOT_FOUND");
       }
       return module;
@@ -132,6 +136,7 @@ export function createTestCompilerHost(
         }
       }
 
+      // eslint-disable-next-line @typescript-eslint/no-deprecated
       throw new TestHostError(`File ${path} not found`, "ENOENT");
     },
 

packages/compiler/src/testing/test-host.ts

@@ -11,7 +11,8 @@ import { addTestLib, StandardTestLibrary } from "./test-compiler-host.js";
 import { createTestWrapper, resolveVirtualPath } from "./test-utils.js";
 import { BasicTestRunner, TestHost, TestHostConfig, TypeSpecTestLibrary } from "./types.js";
 
-/** Use {@link createTester} */
+/* eslint-disable @typescript-eslint/no-deprecated -- implementing deprecated APIs for backward compatibility */
+/** @deprecated Use {@link createTester} */
 export async function createTestHost(config: TestHostConfig = {}): Promise<TestHost> {
   const testHost = await createTestHostInternal();
   await testHost.addTypeSpecLibrary(StandardTestLibrary);
@@ -23,7 +24,7 @@ export async function createTestHost(config: TestHostConfig = {}): Promise<TestH
   return testHost;
 }
 
-/** Use {@link createTester} */
+/** @deprecated Use {@link createTester} */
 export async function createTestRunner(host?: TestHost): Promise<BasicTestRunner> {
   const testHost = host ?? (await createTestHost());
   return createTestWrapper(testHost);
@@ -80,6 +81,7 @@ async function createTestHostInternal(): Promise<TestHost> {
     return [testTypes, p.diagnostics];
   }
 }
+/* eslint-enable @typescript-eslint/no-deprecated */
 
 export async function findFilesFromPattern(directory: string, pattern: string): Promise<string[]> {
   const results: string[] = [];

packages/compiler/src/testing/test-utils.ts

@@ -21,15 +21,19 @@ export function resolveVirtualPath(path: string, ...paths: string[]) {
   return resolvePath(rootDir, path, ...paths);
 }
 
-/** Find the package root from the provided file */
+/** Find the package root from the provided file
+ * @deprecated Use {@link createTester} instead
+ */
 export function findTestPackageRoot(fileUrl: string): Promise<string> {
   return findProjectRoot(NodeHost.stat, fileURLToPath(fileUrl)) as Promise<string>;
 }
 /**
  * Define a test library defaulting to the most common library structure.
  * @param init Library configuration.
  * @returns TypeSpec Test library.
+ * @deprecated Use {@link createTester} instead
  */
+// eslint-disable-next-line @typescript-eslint/no-deprecated
 export function createTestLibrary(init: TypeSpecTestLibraryInit): TypeSpecTestLibrary {
   const { name } = init;
   const typespecFileFolder = init.typespecFileFolder ?? "lib";
@@ -53,6 +57,7 @@ export function createTestLibrary(init: TypeSpecTestLibraryInit): TypeSpecTestLi
   };
 }
 
+/** @deprecated Use {@link Tester} instead */
 export interface TestWrapperOptions {
   wrapper?: (code: string) => string;
 
@@ -68,6 +73,8 @@ export interface TestWrapperOptions {
 
   compilerOptions?: CompilerOptions;
 }
+/** @deprecated Use {@link createTester} instead */
+/* eslint-disable @typescript-eslint/no-deprecated -- implementing deprecated API for backward compatibility */
 export function createTestWrapper(
   host: TestHost,
   testWrapperOptions: TestWrapperOptions = {},
@@ -111,6 +118,7 @@ export function createTestWrapper(
     },
   };
 }
+/* eslint-enable @typescript-eslint/no-deprecated */
 
 export function trimBlankLines(code: string) {
   let start = 0;

packages/compiler/src/testing/types.ts

@@ -38,6 +38,7 @@ export interface TestFileSystem {
   addRealTypeSpecFile(path: string, realPath: string): Promise<void>;
   addRealJsFile(path: string, realPath: string): Promise<void>;
   addRealFolder(path: string, realPath: string): Promise<void>;
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
   addTypeSpecLibrary(testLibrary: TypeSpecTestLibrary): Promise<void>;
 
   /** @internal */
@@ -220,6 +221,8 @@ export interface PositionedMarkerInFile extends PositionedMarker {
 // #endregion
 
 // #region Legacy Test host
+/* eslint-disable @typescript-eslint/no-deprecated -- defining deprecated APIs for backward compatibility */
+/** @deprecated Use {@link Tester} */
 export interface TestHost extends Pick<
   TestFileSystem,
   | "addTypeSpecFile"
@@ -243,12 +246,14 @@ export interface TestHost extends Pick<
   ): Promise<[Record<string, Type>, readonly Diagnostic[]]>;
 }
 
+/** @deprecated Use {@link Tester} */
 export interface TestFiles {
   realDir: string;
   pattern: string;
   virtualPath: string;
 }
 
+/** @deprecated Use {@link Tester} */
 export interface TypeSpecTestLibraryInit {
   name: string;
   packageRoot: string;
@@ -263,16 +268,19 @@ export interface TypeSpecTestLibraryInit {
   jsFileFolder?: string;
 }
 
+/** @deprecated Use {@link Tester} */
 export interface TypeSpecTestLibrary {
   name: string;
   packageRoot: string;
   files: TestFiles[];
 }
 
+/** @deprecated Use {@link Tester} */
 export interface TestHostConfig {
   libraries?: TypeSpecTestLibrary[];
 }
 
+/** @deprecated Use {@link Tester} */
 export class TestHostError extends Error {
   constructor(
     message: string,
@@ -282,6 +290,7 @@ export class TestHostError extends Error {
   }
 }
 
+/** @deprecated Use {@link TesterInstance} */
 export interface BasicTestRunner {
   readonly program: Program;
   readonly fs: Map<string, string>;
@@ -309,4 +318,5 @@ export interface BasicTestRunner {
     options?: CompilerOptions,
   ): Promise<[Record<string, Type>, readonly Diagnostic[]]>;
 }
+/* eslint-enable @typescript-eslint/no-deprecated */
 // #endregion

packages/compiler/templates/scaffolding.json

@@ -124,10 +124,6 @@
         "path": "library-ts/src/rules/no-interfaces.rule.ts",
         "destination": "src/rules/no-interfaces.rule.ts"
       },
-      {
-        "path": "library-ts/src/testing/index.ts.mu",
-        "destination": "src/testing/index.ts"
-      },
       {
         "path": "library-ts/test/decorators.test.ts.mu",
         "destination": "test/decorators.test.ts"
@@ -185,10 +181,6 @@
         "path": "emitter-ts/src/lib.ts",
         "destination": "src/lib.ts"
       },
-      {
-        "path": "emitter-ts/src/testing/index.ts.mu",
-        "destination": "src/testing/index.ts"
-      },
       {
         "path": "emitter-ts/test/hello.test.ts",
         "destination": "test/hello.test.ts"

packages/emitter-framework/src/testing/index.ts

@@ -2,6 +2,7 @@ import { resolvePath } from "@typespec/compiler";
 import { createTestLibrary, type TypeSpecTestLibrary } from "@typespec/compiler/testing";
 import { fileURLToPath } from "url";
 
+/** @deprecated Use `createTester` from `@typespec/compiler/testing` instead */
 export const EmitterFrameworkTestLibrary: TypeSpecTestLibrary = createTestLibrary({
   name: "@typespec/emitter-framework",
   packageRoot: resolvePath(fileURLToPath(import.meta.url), "../../../"),

packages/events/src/testing/index.ts

@@ -1,6 +1,9 @@
 import { createTestLibrary, findTestPackageRoot } from "@typespec/compiler/testing";
 
+/** @deprecated Use `createTester` from `@typespec/compiler/testing` instead */
+/* eslint-disable @typescript-eslint/no-deprecated */
 export const EventsTestLibrary = createTestLibrary({
   name: "@typespec/events",
   packageRoot: await findTestPackageRoot(import.meta.url),
 });
+/* eslint-enable @typescript-eslint/no-deprecated */

packages/html-program-viewer/src/testing/index.ts

@@ -4,8 +4,11 @@ import {
   type TypeSpecTestLibrary,
 } from "@typespec/compiler/testing";
 
+/** @deprecated Use `createTester` from `@typespec/compiler/testing` instead */
+/* eslint-disable @typescript-eslint/no-deprecated */
 export const ProgramViewerTestLibrary: TypeSpecTestLibrary = createTestLibrary({
   name: "@typespec/html-program-viewer",
   jsFileFolder: "dist/emitter",
   packageRoot: await findTestPackageRoot(import.meta.url),
 });
+/* eslint-enable @typescript-eslint/no-deprecated */

packages/http-client-js/src/testing/index.ts

@@ -2,6 +2,7 @@ import { resolvePath } from "@typespec/compiler";
 import { createTestLibrary, TypeSpecTestLibrary } from "@typespec/compiler/testing";
 import { fileURLToPath } from "url";
 
+/** @deprecated Use `createTester` from `@typespec/compiler/testing` instead */
 export const HttpClientJavascriptEmitterTestLibrary: TypeSpecTestLibrary = createTestLibrary({
   name: "@typespec/http-client-js",
   packageRoot: resolvePath(fileURLToPath(import.meta.url), "../../../"),

packages/http-client/src/testing/index.ts

@@ -2,6 +2,7 @@ import { resolvePath } from "@typespec/compiler";
 import { createTestLibrary, TypeSpecTestLibrary } from "@typespec/compiler/testing";
 import { fileURLToPath } from "url";
 
+/** @deprecated Use `createTester` from `@typespec/compiler/testing` instead */
 export const HttpClientTestLibrary: TypeSpecTestLibrary = createTestLibrary({
   name: "@typespec/http-client",
   packageRoot: resolvePath(fileURLToPath(import.meta.url), "../../../../"),

packages/http-server-js/src/testing/index.ts

@@ -4,7 +4,10 @@ import {
   findTestPackageRoot,
 } from "@typespec/compiler/testing";
 
+/** @deprecated Use `createTester` from `@typespec/compiler/testing` instead */
+/* eslint-disable @typescript-eslint/no-deprecated */
 export const HttpServerJavaScriptTestLibrary: TypeSpecTestLibrary = createTestLibrary({
   name: "@typespec/http-server-js",
   packageRoot: await findTestPackageRoot(import.meta.url),
 });
+/* eslint-enable @typescript-eslint/no-deprecated */