chore: deprecate doc itests (#25452)

tests/integration/doc_tests.rs

@@ -1,145 +0,0 @@
-// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
-
-use test_util as util;
-use test_util::itest;
-use util::assert_contains;
-use util::TestContext;
-
-itest!(deno_doc_builtin {
-  args: "doc",
-  output: "doc/deno_doc_builtin.out",
-});
-
-#[test]
-fn deno_doc() {
-  let context = TestContext::default();
-  // try this twice to ensure it works with the cache
-  for _ in 0..2 {
-    let output = context
-      .new_command()
-      .env("NO_COLOR", "1")
-      .args("doc doc/deno_doc.ts doc/deno_doc2.ts")
-      .split_output()
-      .run();
-
-    output.assert_exit_code(0);
-    assert_contains!(output.stdout(), "function foo");
-    assert_contains!(output.stdout(), "function bar");
-  }
-}
-
-itest!(deno_doc_import_map {
-  args: "doc --import-map=doc/import_map.json doc/use_import_map.js",
-  output: "doc/use_import_map.out",
-});
-
-itest!(deno_doc_types_hint {
-  args: "doc doc/types_hint.ts",
-  output: "doc/types_hint.out",
-});
-
-itest!(deno_doc_types_ref {
-  args: "doc doc/types_ref.js",
-  output: "doc/types_ref.out",
-});
-
-itest!(deno_doc_types_header {
-  args: "doc --reload doc/types_header.ts",
-  output: "doc/types_header.out",
-  http_server: true,
-});
-
-itest!(deno_doc_referenced_private_types {
-  args: "doc doc/referenced_private_types.ts",
-  output: "doc/referenced_private_types.out",
-});
-
-itest!(deno_doc_lint_referenced_private_types_error {
-  args: "doc --lint doc/referenced_private_types.ts",
-  exit_code: 1,
-  output: "doc/referenced_private_types_lint.out",
-});
-
-itest!(deno_doc_lint_referenced_private_types_fixed {
-  args: "doc --lint doc/referenced_private_types_fixed.ts",
-  output: "doc/referenced_private_types_fixed.out",
-});
-
-itest!(deno_doc_html_lint_referenced_private_types_fixed {
-  args: "doc --lint --html --name=Library doc/referenced_private_types.ts",
-  exit_code: 1,
-  output: "doc/referenced_private_types_lint.out",
-});
-
-itest!(deno_doc_lint_success {
-  args: "doc --lint doc/lint_success.ts",
-  output: "doc/lint_success.out",
-});
-
-itest!(deno_doc_lint_json_success {
-  args: "doc --lint --json doc/lint_success.ts",
-  output: "doc/lint_success_json.out",
-});
-
-itest!(deno_doc_lint_html_success {
-  args: "doc --lint --html --name=Library lint_success.ts",
-  copy_temp_dir: Some("doc"),
-  cwd: Some("doc"),
-  output: "doc/lint_success_html.out",
-});
-
-itest!(_060_deno_doc_displays_all_overloads_in_details_view {
-  args:
-    "doc --filter NS.test doc/060_deno_doc_displays_all_overloads_in_details_view.ts",
-  output: "doc/060_deno_doc_displays_all_overloads_in_details_view.ts.out",
-});
-
-itest!(deno_doc_types_header_direct {
-  args: "doc --reload http://127.0.0.1:4545/xTypeScriptTypes.js",
-  output: "doc/types_header.out",
-  http_server: true,
-});
-
-itest!(deno_doc_invalid_url {
-  args: "doc https://raw.githubusercontent.com%2Fdyedgreen%2Fdeno-sqlite%2Frework_api%2Fmod.ts",
-  output: "doc/invalid_url.out",
-  exit_code: 1,
-});
-
-#[test]
-fn deno_doc_html() {
-  let context = TestContext::default();
-  let temp_dir = context.temp_dir();
-  let output = context
-    .new_command()
-    .env("NO_COLOR", "1")
-    .args_vec(vec![
-      "doc",
-      "--html",
-      "--name=MyLib",
-      &format!("--output={}", temp_dir.path().to_string_lossy()),
-      "doc/referenced_private_types_fixed.ts",
-    ])
-    .split_output()
-    .run();
-
-  output.assert_exit_code(0);
-  assert_contains!(output.stderr(), "Written 14 files to");
-  assert!(temp_dir.path().join("all_symbols.html").exists());
-  assert!(temp_dir.path().join("index.html").exists());
-  assert!(temp_dir.path().join("fuse.js").exists());
-  assert!(temp_dir.path().join("page.css").exists());
-  assert!(temp_dir.path().join("reset.css").exists());
-  assert!(temp_dir.path().join("script.js").exists());
-  assert!(temp_dir.path().join("search.js").exists());
-  assert!(temp_dir.path().join("search_index.js").exists());
-  assert!(temp_dir.path().join("styles.css").exists());
-  assert!(temp_dir.path().join("~/MyInterface.html").exists());
-  assert!(temp_dir.path().join("~/MyInterface.prop.html").exists());
-  assert!(temp_dir.path().join("~/MyClass.html").exists());
-  assert!(temp_dir.path().join("~/MyClass.prototype.html").exists());
-  assert!(temp_dir
-    .path()
-    .join("~/MyClass.prototype.prop.html")
-    .exists());
-}

tests/integration/mod.rs

@@ -17,8 +17,6 @@ mod check;
 mod compile;
 #[path = "coverage_tests.rs"]
 mod coverage;
-#[path = "doc_tests.rs"]
-mod doc;
 #[path = "eval_tests.rs"]
 mod eval;
 #[path = "flags_tests.rs"]

tests/specs/doc/_060_deno_doc_displays_all_overloads_in_details_view/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc --filter NS.test 060_deno_doc_displays_all_overloads_in_details_view.ts",
+  "output": "060_deno_doc_displays_all_overloads_in_details_view.ts.out"
+}

tests/specs/doc/builtin/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc",
+  "output": "deno_doc_builtin.out"
+}

tests/specs/doc/deno_doc/__test__.jsonc

@@ -0,0 +1,17 @@
+{
+  "steps": [{
+    "args": "doc deno_doc.ts",
+    "output": "foo.out",
+    "exitCode": 0,
+    "envs": {
+      "NO_COLOR": "1"
+    }
+  }, {
+    "args": "doc deno_doc2.ts",
+    "output": "bar.out",
+    "exitCode": 0,
+    "envs": {
+      "NO_COLOR": "1"
+    }
+  }]
+}

tests/specs/doc/deno_doc/bar.out

@@ -0,0 +1,5 @@
+Defined in [WILDCARD]/deno_doc2.ts:2:1
+
+function bar(): void
+  Some JSDoc
+

tests/specs/doc/deno_doc/foo.out

@@ -0,0 +1,5 @@
+Defined in [WILDCARD]/deno_doc.ts:2:1
+
+function foo(): void
+  Some JSDoc
+

tests/specs/doc/html/__test__.jsonc

@@ -0,0 +1,12 @@
+{
+  "tempDir": true,
+  "args": [
+    "doc",
+    "--html",
+    "--name=MyLib",
+    "--output=temp_dir_path_here",
+    "referenced_private_types_fixed.ts"
+  ],
+  "output": "[WILDCARD]",
+  "exitCode": 0
+}

tests/specs/doc/html_lint_referenced_private_types_fixed/__test__.jsonc

@@ -0,0 +1,5 @@
+{
+  "args": "doc --lint --html --name=Library referenced_private_types.ts",
+  "output": "referenced_private_types_lint.out",
+  "exitCode": 1
+}

tests/specs/doc/import_map/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc --import-map=import_map.json use_import_map.js",
+  "output": "use_import_map.out"
+}

tests/specs/doc/import_map/use_import_map.out

@@ -1,4 +1,4 @@
-Defined in [WILDCARD]/doc/module/fun.js:2:1
+Defined in [WILDCARD]/module/fun.js:2:1
 
 function fun(_a, _b): void
   This is some documentation

tests/specs/doc/invalid_url/__test__.jsonc

@@ -0,0 +1,5 @@
+{
+  "args": "doc https://raw.githubusercontent.com%2Fdyedgreen%2Fdeno-sqlite%2Frework_api%2Fmod.ts",
+  "output": "invalid_url.out",
+  "exitCode": 1
+}

tests/specs/doc/lint_html_success/__test__.jsonc

@@ -0,0 +1,5 @@
+{
+  "tempDir": true,
+  "args": "doc --lint --html --name=Library lint_success.ts",
+  "output": "lint_success_html.out"
+}

tests/specs/doc/lint_json_success/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc --lint --json lint_success.ts",
+  "output": "lint_success_json.out"
+}

tests/specs/doc/lint_json_success/lint_success.ts

@@ -0,0 +1,5 @@
+/** My test class. */
+export class Test {
+  /** My property. */
+  prop: string;
+}

tests/specs/doc/lint_referenced_private_types_error/__test__.jsonc

@@ -0,0 +1,5 @@
+{
+  "args": "doc --lint referenced_private_types.ts",
+  "exitCode": 1,
+  "output": "referenced_private_types_lint.out"
+}

tests/specs/doc/lint_referenced_private_types_error/referenced_private_types.ts

@@ -0,0 +1,7 @@
+interface MyInterface {
+  prop?: string;
+}
+
+export class MyClass {
+  prop: MyInterface = {};
+}

tests/specs/doc/lint_referenced_private_types_error/referenced_private_types_lint.out

@@ -0,0 +1,29 @@
+error[missing-jsdoc]: exported symbol is missing JSDoc documentation
+ --> [WILDCARD]:5:1
+  | 
+5 | export class MyClass {
+  | ^
+
+
+error[private-type-ref]: public type 'MyClass.prototype.prop' references private type 'MyInterface'
+ --> [WILDCARD]:6:3
+  | 
+6 |   prop: MyInterface = {};
+  |   ^
+  = hint: make the referenced type public or remove the reference
+  | 
+1 | interface MyInterface {
+  | - this is the referenced type
+  | 
+
+  info: to ensure documentation is complete all types that are exposed in the public API must be public
+
+
+error[missing-jsdoc]: exported symbol is missing JSDoc documentation
+ --> [WILDCARD]:6:3
+  | 
+6 |   prop: MyInterface = {};
+  |   ^
+
+
+error: Found 3 documentation lint errors.

tests/specs/doc/lint_referenced_private_types_fixed/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc --lint referenced_private_types_fixed.ts",
+  "output": "referenced_private_types_fixed.out"
+}

tests/specs/doc/lint_referenced_private_types_fixed/referenced_private_types_fixed.ts

@@ -0,0 +1,11 @@
+/** Doc comment */
+export interface MyInterface {
+  /** Doc comment */
+  prop?: string;
+}
+
+/** Doc comment */
+export class MyClass {
+  /** Doc comment */
+  prop: MyInterface = {};
+}

tests/specs/doc/lint_success/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc --lint lint_success.ts",
+  "output": "lint_success.out"
+}

tests/specs/doc/lint_success/lint_success.ts

@@ -0,0 +1,5 @@
+/** My test class. */
+export class Test {
+  /** My property. */
+  prop: string;
+}

tests/specs/doc/referenced_private_types/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc referenced_private_types.ts",
+  "output": "referenced_private_types.out"
+}

tests/specs/doc/referenced_private_types/referenced_private_types.out

@@ -0,0 +1,12 @@
+Defined in file:///[WILDCARD]/referenced_private_types.ts:5:1
+
+class MyClass
+
+  prop: MyInterface
+
+Defined in file:///[WILDCARD]/referenced_private_types.ts:1:1
+
+private interface MyInterface
+
+  prop?: string
+

tests/specs/doc/referenced_private_types/referenced_private_types.ts

@@ -0,0 +1,7 @@
+interface MyInterface {
+  prop?: string;
+}
+
+export class MyClass {
+  prop: MyInterface = {};
+}

tests/specs/doc/types_header/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc --reload types_header.ts",
+  "output": "types_header.out"
+}

tests/specs/doc/types_header_direct/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc --reload http://127.0.0.1:4545/xTypeScriptTypes.js",
+  "output": "types_header.out"
+}

tests/specs/doc/types_header_direct/types_header.out

@@ -0,0 +1,6 @@
+Download http://127.0.0.1:4545/xTypeScriptTypes.js
+Download http://127.0.0.1:4545/xTypeScriptTypes.d.ts
+Defined in http://127.0.0.1:4545/xTypeScriptTypes.d.ts:1:14
+
+const foo: "foo"
+

tests/specs/doc/types_hint/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc types_hint.ts",
+  "output": "types_hint.out"
+}

tests/specs/doc/types_hint/foo.d.ts

@@ -0,0 +1,2 @@
+/** An exported value. */
+export const foo: string;

tests/specs/doc/types_hint/foo.js

@@ -0,0 +1 @@
+export const foo = "foo";

tests/specs/doc/types_hint/types_hint.out

@@ -0,0 +1,5 @@
+Defined in [WILDCARD]/foo.d.ts:2:14
+
+const foo: string
+  An exported value.
+

tests/specs/doc/types_hint/types_hint.ts

@@ -0,0 +1,2 @@
+// @deno-types="./foo.d.ts"
+export * from "./foo.js";

tests/specs/doc/types_ref/__test__.jsonc

@@ -0,0 +1,4 @@
+{
+  "args": "doc types_ref.js",
+  "output": "types_ref.out"
+}

tests/specs/doc/types_ref/foo.d.ts

@@ -0,0 +1,2 @@
+/** An exported value. */
+export const foo: string;

tests/specs/doc/types_ref/types_ref.js

@@ -0,0 +1,2 @@
+/// <reference types="./foo.d.ts" />
+export const foo = "foo";

tests/specs/doc/types_ref/types_ref.out

@@ -0,0 +1,5 @@
+Defined in [WILDCARD]/foo.d.ts:2:14
+
+const foo: string
+  An exported value.
+

tests/testdata/doc/referenced_private_types.out

@@ -1,12 +0,0 @@
-Defined in file:///[WILDCARD]/doc/referenced_private_types.ts:5:1
-
-class MyClass
-
-  prop: MyInterface
-
-Defined in file:///[WILDCARD]/doc/referenced_private_types.ts:1:1
-
-private interface MyInterface
-
-  prop?: string
-

tests/testdata/doc/types_hint.out

@@ -1,5 +0,0 @@
-Defined in [WILDCARD]/type_definitions/foo.d.ts:2:14
-
-const foo: string
-  An exported value.
-

tests/testdata/doc/types_hint.ts

@@ -1,2 +0,0 @@
-// @deno-types="../type_definitions/foo.d.ts"
-export * from "../type_definitions/foo.js";

tests/testdata/doc/types_ref.js

@@ -1,2 +0,0 @@
-/// <reference types="../type_definitions/foo.d.ts" />
-export const foo = "foo";

tests/testdata/doc/types_ref.out

@@ -1,5 +0,0 @@
-Defined in [WILDCARD]/type_definitions/foo.d.ts:2:14
-
-const foo: string
-  An exported value.
-

tools/lint.js

@@ -201,7 +201,6 @@ async function ensureNoNewITests() {
     "check_tests.rs": 22,
     "compile_tests.rs": 0,
     "coverage_tests.rs": 0,
-    "doc_tests.rs": 15,
     "eval_tests.rs": 0,
     "flags_tests.rs": 0,
     "fmt_tests.rs": 17,