Add unit tests for remark/rehype plugins

See #17 Migrate unit tests for our custom remark and rehype plugins from the archived `gravitational/docs` repo. Convert these tests to Jest, which unlike the uvu testing tool we used for `gravitational/docs`, is still being maintained. Add a GitHub Actions workflow to run the tests on pull requests. To get the `remark-includes` test to pass, edit the `updatePaths` function to only extract a version number from the path of a partial if the partial falls under a directory path for production content.
gravitational · Jan 29, 2025 · 1021c27 · 1021c27
1 parent 3530123
commit 1021c27
Show file tree

Hide file tree

Showing 66 changed files with 3,598 additions and 52 deletions.
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -0,0 +1,11 @@
+name: Test
+on:
+  pull_request:
+
+jobs:
+  run-tests:
+    name: Run tests
+    runs-on: ubuntu-22.04-2core-arm64
+    steps:
+    - uses: actions/checkout@v4
+    - run: yarn && yarn test
diff --git a/babel.config.js b/babel.config.js
diff --git a/jest.server.config.js b/jest.server.config.js
@@ -0,0 +1,17 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+const jestConfig = {
+  preset: "ts-jest/presets/default-esm",
+  testEnvironment: "node",
+  extensionsToTreatAsEsm: [".ts"],
+  transform: {
+    "^.+\\.[tj]s$": [
+      "ts-jest",
+      {
+        useESM: true,
+        tsconfig: "tsconfig.node.json",
+      },
+    ],
+  },
+  transformIgnorePatterns: ["<rootDir>/node_modules/*"],
+};
+export default jestConfig;
diff --git a/package.json b/package.json
@@ -1,10 +1,11 @@
 {
   "name": "docusaurus",
+  "type": "module",
   "version": "0.0.0",
   "private": true,
   "scripts": {
     "spellcheck": "bash scripts/check-spelling.sh",
-    "build-remark": "rm -rf .remark-build && tsc --build tsconfig.node.json && tsc-esm-fix --target='.remark-build' --ext='.mjs'",
+    "build-remark": "tsc --build tsconfig.node.json && tsc-esm-fix --target='.remark-build' --ext='.mjs'",
     "git-update": "scripts/update_submodules.sh",
     "prepare-files": "npx vite-node ./scripts/prepare-files.mts",
     "prepare-sanity-data": "npx vite-node ./scripts/prepare-sanity-data.mts",
@@ -18,12 +19,12 @@
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc --noEmit --skipLibCheck --incremental --tsBuildInfoFile node_modules/.cache/tsc/tsbuildinfo --project .",
-    "uvu-test": "loadr -- uvu uvu-tests",
     "base:eslint": "eslint --cache --cache-location node_modules/.cache/eslint '**/*.{js,jsx,ts,tsx}'",
     "base:prettier": "prettier '**/*.{js,jsx,ts,tsx,json}'",
     "lint": "yarn base:eslint --fix && yarn base:prettier --write -l",
     "lint-check": "yarn base:eslint && yarn base:prettier --check",
-    "markdown-lint": "yarn build-remark && remark --rc-path .remarkrc.mjs 'content/**/docs/pages/**/*.mdx' --quiet --frail --ignore-pattern '**/includes/**' --silently-ignore"
+    "markdown-lint": "yarn build-remark && remark --rc-path .remarkrc.mjs 'content/**/docs/pages/**/*.mdx' --quiet --frail --ignore-pattern '**/includes/**' --silently-ignore",
+    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --trace-warnings --experimental-vm-modules\" jest --config ./jest.server.config.js server/*.test.ts"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": [
@@ -62,10 +63,12 @@
     "@docusaurus/plugin-client-redirects": "^3.6.3",
     "@docusaurus/tsconfig": "^3.6.3",
     "@docusaurus/types": "^3.6.3",
+    "@types/jest": "^29.5.14",
     "@types/react": "^18.3.3",
     "ajv": "^8.16.0",
     "dotenv": "^16.4.5",
     "hast": "^1.0.0",
+    "jest": "^29.7.0",
     "js-yaml": "^4.1.0",
     "loadr": "^0.1.1",
     "mdast": "^3.0.0",
@@ -91,15 +94,16 @@
     "remark-rehype": "^10.1.0",
     "remark-validate-links": "^11.0.2",
     "to-vfile": "^8.0.0",
+    "ts-jest": "^29.2.5",
     "tsc-esm-fix": "^3.1.0",
     "tsm": "^2.3.0",
-    "typescript": "~5.5.2",
+    "typescript": "^5.7.3",
     "unified": "^11.0.5",
     "unified-lint-rule": "^3.0.0",
     "unist": "^0.0.1",
     "unist-util-find": "^3.0.0",
     "unist-util-visit-parents": "^6.0.1",
-    "vfile": "^6.0.1",
+    "vfile": "^6.0.3",
     "vite-node": "^3.0.4"
   },
   "browserslist": {

diff --git a/server/asset-path-helpers.ts b/server/asset-path-helpers.ts
@@ -15,6 +15,9 @@ const REGEXP_POST_PREPARE_VERSION = /^\/versioned_docs\/version-([^\/]+)\//;
 // migration script
 const REGEXP_PRE_PREPARE_VERSION = /^\/?content\/([^\/]+)\//;
 const REGEXP_EXTENSION = /(\/index)?\.mdx$/;
+// Matches content directory paths we use for building the docs site (versus for
+// testing).
+const REGEXP_CONTENT_DIR_PATH = /^(\/(versioned_)?docs|\/?content)\//;
 
 export type DocsMeta = {
   isCurrent: boolean;
@@ -73,8 +76,12 @@ const getCurrentDir = (vfile: VFile) => {
 const getPagesDir = (vfile: VFile): string =>
   resolve(getRootDir(vfile), "docs/pages");
 
-const getOriginalPath = (vfile: VFile) =>
-  vfile.path.replace(getCurrentDir(vfile), getPagesDir(vfile));
+const getOriginalPath = (vfile: VFile) => {
+  if (vfile.path.match(REGEXP_CONTENT_DIR_PATH)) {
+    return vfile.path.replace(getCurrentDir(vfile), getPagesDir(vfile));
+  }
+  return vfile.path;
+};
 
 const extBlackList = ["md", "mdx"];
 
@@ -136,24 +143,23 @@ export const updatePathsInIncludes = ({
       return href;
     }
 
+    let absTargetPath = resolve(versionRootDir, dirname(includePath), href);
     if (node.type === "link") {
       const absMdxPath = dirname(vfile.path);
 
-      const absTargetPath = resolve(
-        versionRootDir,
-        dirname(includePath),
-        href
-      ).replace(getPagesDir(vfile), getCurrentDir(vfile));
+      if (vfile.path.match(REGEXP_CONTENT_DIR_PATH)) {
+        absTargetPath = absTargetPath.replace(
+          getPagesDir(vfile),
+          getCurrentDir(vfile)
+        );
+      }
 
       (node as Link | Image | Definition).url = relative(
         absMdxPath,
         absTargetPath
       );
     } else {
       const absMdxPath = resolve(getOriginalPath(vfile));
-
-      const absTargetPath = resolve(versionRootDir, dirname(includePath), href);
-
       (node as Link | Image | Definition).url = relative(
         dirname(absMdxPath),
         absTargetPath

diff --git a/server/fixtures/code-snippet-empty-line.mdx b/server/fixtures/code-snippet-empty-line.mdx
@@ -0,0 +1,16 @@
+```code
+$ tsh request search --kind node
+Name                                 Hostname    Labels       Resource ID
+------------------------------------ ----------- ------------
+------------------------------------------------------
+b1168402-9340-421a-a344-af66a6675738 iot         test=test
+/teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738
+bbb56211-7b54-4f9e-bee9-b68ea156be5f node        test=test
+/teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f
+
+To request access to these resources, run
+> tsh request create --resource
+> /teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738 --resource
+> /teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f \
+>     --reason <request reason>
+```
diff --git a/server/fixtures/go-comment-var.mdx b/server/fixtures/go-comment-var.mdx
@@ -0,0 +1,8 @@
+```go
+// This is a comment about the code below, which contains a 
+// <Var name="myvar" />. This comment also includes another 
+// <Var name="othervar" />. This is the end of the comment.
+func myfunc(attr string) error {
+  return nil
+}
+```
diff --git a/server/fixtures/hcl-addr-var.mdx b/server/fixtures/hcl-addr-var.mdx
@@ -0,0 +1,29 @@
+1. Create a `main.tf` file containing this minimal Terraform code:
+
+   ```hcl
+   terraform {
+     required_providers {
+       teleport = {
+         source  = "terraform.releases.teleport.dev/gravitational/teleport"
+         version = "~> (=teleport.major_version=).0"
+       }
+     }
+   }
+   
+   provider "teleport" {
+     addr               = '<Var name="teleport.example.com:443" />'
+   }
+   ```
+
+1. Then, init your Terraform working directory to download the Teleport provider:
+
+   ```code
+   $ terraform init
+   Initializing the backend...
+   
+   Initializing provider plugins...
+   - Finding terraform.releases.teleport.dev/gravitational/teleport versions matching ...
+   ```
+
+1. Finally, run a Terraform plan:
+
diff --git a/server/fixtures/hcl-vars.mdx b/server/fixtures/hcl-vars.mdx
@@ -0,0 +1,11 @@
+Assign <Var name="proxy" initial="teleport.example.com:443" /> to the address of
+your Teleport Proxy Service.
+
+```hcl
+provider "teleport" {
+  # Update addr to point to your Teleport Cloud tenant URL's host:port
+  addr               = "<Var name="proxy" />"
+  identity_file_path = "terraform-identity"
+}
+```
+
diff --git a/server/fixtures/includes-multiple-result.mdx b/server/fixtures/includes-multiple-result.mdx
@@ -0,0 +1,39 @@
+## Example code block
+
+Code block with multiple includes.
+
+```css
+.example1 {
+  width: 50%;
+  height: 50%;
+}
+
+.base {
+  width: 100%;
+  height: 100%;
+}
+
+.base {
+  width: 100%;
+  height: 100%;
+}
+
+.example2 {
+  width: 50%;
+  height: 50%;
+}
+
+.base {
+  width: 100%;
+  height: 100%;
+}
+
+```
+
+## Example test block
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
diff --git a/server/fixtures/includes-multiple-source.mdx b/server/fixtures/includes-multiple-source.mdx
@@ -0,0 +1,27 @@
+## Example code block
+
+Code block with multiple includes.
+
+```css
+.example1 {
+  width: 50%;
+  height: 50%;
+}
+
+(!include.css!)
+(!include.css!)
+.example2 {
+  width: 50%;
+  height: 50%;
+}
+
+(!include.css!)
+```
+
+## Example test block
+
+(!include-string.mdx!)
+
+(!include-string.mdx!)
+
+(!include-string.mdx!)
diff --git a/server/fixtures/includes-result.mdx b/server/fixtures/includes-result.mdx
@@ -0,0 +1,64 @@
+## Header
+
+```css
+.base {
+  width: 100%;
+  height: 100%;
+}
+
+```
+
+```css
+/* Some text inside codeblock before */
+
+.base {
+  width: 100%;
+  height: 100%;
+}
+
+
+/* And after */
+```
+
+```md
+| OPERATING SYSTEM                          | CHECKSUM                                                                                              | DOWNLOAD LINK                                                                                                                                  |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Linux 32-bit                              | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-386-bin.tar.gz.sha256)           | [teleport-v6.0.0-alpha.2-linux-386-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-386-bin.tar.gz)                     |
+| Linux 64-bit                              | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-bin.tar.gz.sha256)         | [teleport-v6.0.0-alpha.2-linux-amd64-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-bin.tar.gz)                 |
+| Linux 64-bit (RHEL/CentOS 6.x compatible) | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-centos6-bin.tar.gz.sha256) | [teleport-v6.0.0-alpha.2-linux-amd64-centos6-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-centos6-bin.tar.gz) |
+| Linux ARMv7                               | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-arm-bin.tar.gz.sha256)           | [teleport-v6.0.0-alpha.2-linux-arm-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-arm-bin.tar.gz)                     |
+| Linux 64-bit DEB                          | [SHA256](https://get.gravitational.com/teleport_6.0.0-alpha.2_amd64.deb.sha256)                       | [teleport-v6.0.0-alpha.2-amd64.deb](https://get.gravitational.com/teleport_6.0.0-alpha.2_amd64.deb)                                            |
+| Linux 32-bit DEB                          | [SHA256](https://get.gravitational.com/teleport_6.0.0-alpha.2_i386.deb.sha256)                        | [teleport-v6.0.0-alpha.2-i386.deb](https://get.gravitational.com/teleport_6.0.0-alpha.2_amd64.deb)                                             |
+| Linux 64-bit RPM                          | [SHA256](https://get.gravitational.com/teleport-6.0.0-alpha.2-1.x86_64.rpm.sha256)                    | [teleport-6.0.0-alpha.2-1.x86-64.rpm](https://get.gravitational.com/teleport-6.0.0-alpha.2-1.x86_64.rpm)                                       |
+| Docker Image                              | [SHA256](https://quay.io/repository/gravitational/teleport?tab=tags)                                  | `docker pull quay.io/gravitational/teleport:6.0.0-alpha.2`                                                                                     |
+```
+
+| OPERATING SYSTEM                          | CHECKSUM                                                                                              | DOWNLOAD LINK                                                                                                                                  |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Linux 32-bit                              | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-386-bin.tar.gz.sha256)           | [teleport-v6.0.0-alpha.2-linux-386-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-386-bin.tar.gz)                     |
+| Linux 64-bit                              | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-bin.tar.gz.sha256)         | [teleport-v6.0.0-alpha.2-linux-amd64-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-bin.tar.gz)                 |
+| Linux 64-bit (RHEL/CentOS 6.x compatible) | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-centos6-bin.tar.gz.sha256) | [teleport-v6.0.0-alpha.2-linux-amd64-centos6-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-centos6-bin.tar.gz) |
+| Linux ARMv7                               | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-arm-bin.tar.gz.sha256)           | [teleport-v6.0.0-alpha.2-linux-arm-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-arm-bin.tar.gz)                     |
+| Linux 64-bit DEB                          | [SHA256](https://get.gravitational.com/teleport_6.0.0-alpha.2_amd64.deb.sha256)                       | [teleport-v6.0.0-alpha.2-amd64.deb](https://get.gravitational.com/teleport_6.0.0-alpha.2_amd64.deb)                                            |
+| Linux 32-bit DEB                          | [SHA256](https://get.gravitational.com/teleport_6.0.0-alpha.2_i386.deb.sha256)                        | [teleport-v6.0.0-alpha.2-i386.deb](https://get.gravitational.com/teleport_6.0.0-alpha.2_amd64.deb)                                             |
+| Linux 64-bit RPM                          | [SHA256](https://get.gravitational.com/teleport-6.0.0-alpha.2-1.x86_64.rpm.sha256)                    | [teleport-6.0.0-alpha.2-1.x86-64.rpm](https://get.gravitational.com/teleport-6.0.0-alpha.2-1.x86_64.rpm)                                       |
+| Docker Image                              | [SHA256](https://quay.io/repository/gravitational/teleport?tab=tags)                                  | `docker pull quay.io/gravitational/teleport:6.0.0-alpha.2`                                                                                     |
+
+Some text before (!include-table.mdx!) and after
+
+(!non-existing.mdx!)
+
+<Tabs>
+  <TabItem label="Include inside tab">
+    | OPERATING SYSTEM                          | CHECKSUM                                                                                              | DOWNLOAD LINK                                                                                                                                  |
+    | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+    | Linux 32-bit                              | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-386-bin.tar.gz.sha256)           | [teleport-v6.0.0-alpha.2-linux-386-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-386-bin.tar.gz)                     |
+    | Linux 64-bit                              | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-bin.tar.gz.sha256)         | [teleport-v6.0.0-alpha.2-linux-amd64-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-bin.tar.gz)                 |
+    | Linux 64-bit (RHEL/CentOS 6.x compatible) | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-centos6-bin.tar.gz.sha256) | [teleport-v6.0.0-alpha.2-linux-amd64-centos6-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-amd64-centos6-bin.tar.gz) |
+    | Linux ARMv7                               | [SHA256](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-arm-bin.tar.gz.sha256)           | [teleport-v6.0.0-alpha.2-linux-arm-bin.tar.gz](https://get.gravitational.com/teleport-v6.0.0-alpha.2-linux-arm-bin.tar.gz)                     |
+    | Linux 64-bit DEB                          | [SHA256](https://get.gravitational.com/teleport_6.0.0-alpha.2_amd64.deb.sha256)                       | [teleport-v6.0.0-alpha.2-amd64.deb](https://get.gravitational.com/teleport_6.0.0-alpha.2_amd64.deb)                                            |
+    | Linux 32-bit DEB                          | [SHA256](https://get.gravitational.com/teleport_6.0.0-alpha.2_i386.deb.sha256)                        | [teleport-v6.0.0-alpha.2-i386.deb](https://get.gravitational.com/teleport_6.0.0-alpha.2_amd64.deb)                                             |
+    | Linux 64-bit RPM                          | [SHA256](https://get.gravitational.com/teleport-6.0.0-alpha.2-1.x86_64.rpm.sha256)                    | [teleport-6.0.0-alpha.2-1.x86-64.rpm](https://get.gravitational.com/teleport-6.0.0-alpha.2-1.x86_64.rpm)                                       |
+    | Docker Image                              | [SHA256](https://quay.io/repository/gravitational/teleport?tab=tags)                                  | `docker pull quay.io/gravitational/teleport:6.0.0-alpha.2`                                                                                     |
+  </TabItem>
+</Tabs>
diff --git a/server/fixtures/includes-source.mdx b/server/fixtures/includes-source.mdx
@@ -0,0 +1,29 @@
+## Header
+
+```css
+(!include.css!)
+```
+
+```css
+/* Some text inside codeblock before */
+
+(!include.css!)
+
+/* And after */
+```
+
+```md
+(!include-table.mdx!)
+```
+
+(!include-table.mdx!)
+
+Some text before (!include-table.mdx!) and after
+
+(!non-existing.mdx!)
+
+<Tabs>
+  <TabItem label="Include inside tab">
+    (!include-table.mdx!)
+  </TabItem>
+</Tabs>
diff --git a/server/fixtures/includes-vars-erroneous-include.mdx b/server/fixtures/includes-vars-erroneous-include.mdx
@@ -0,0 +1,5 @@
+## Installation
+
+Here is a test for including variables in an MDX file.
+
+(!install-version.mdx version="10" unsupport="9" !)