3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 15:47:23 +02:00
Code Issues Projects Releases Packages Wiki Activity

test: improve test coverage; properly test core client APIs (#6905)

Browse source 
* test: improve test coverage

* fix
This commit is contained in:
Joshua Chen 2022-03-12 23:15:45 +08:00 • committed by GitHub
parent 76cb012209
commit d85cee576d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
41 changed files with 1400 additions and 753 deletions
Download patch file Download diff file Expand all files Collapse all files

43
packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/globalData.test.ts.snap Normal file
View file

@ -0,0 +1,43 @@
// Jest Snapshot v1, https://goo.gl/fbAQLP
exports[`toGlobalDataVersion generates the right docs, sidebars, and metadata 1`] = `
Object {
"docs": Array [
Object {
"id": "main",
"path": "/current/main",
"sidebar": "tutorial",
},
Object {
"id": "doc",
"path": "/current/doc",
"sidebar": "tutorial",
},
Object {
"id": "/current/generated",
"path": "/current/generated",
"sidebar": "tutorial",
},
],
"isLast": true,
"label": "Label",
"mainDocId": "main",
"name": "current",
"path": "/current",
"sidebars": Object {
"another": Object {
"link": Object {
"label": "Generated",
"path": "/current/generated",
},
},
"links": Object {},
"tutorial": Object {
"link": Object {
"label": "main",
"path": "/current/main",
},
},
},
}
`;

100
packages/docusaurus-plugin-content-docs/src/__tests__/globalData.test.ts Normal file
View file

@ -0,0 +1,100 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import {toGlobalDataVersion} from '../globalData';
describe('toGlobalDataVersion', () => {
it('generates the right docs, sidebars, and metadata', () => {
expect(
toGlobalDataVersion({
versionName: 'current',
versionLabel: 'Label',
isLast: true,
versionPath: '/current',
mainDocId: 'main',
docs: [
{
unversionedId: 'main',
permalink: '/current/main',
sidebar: 'tutorial',
},
{
unversionedId: 'doc',
permalink: '/current/doc',
sidebar: 'tutorial',
},
],
sidebars: {
another: [
{
type: 'category',
label: 'Generated',
link: {
type: 'generated-index',
permalink: '/current/generated',
},
items: [
{
type: 'doc',
id: 'doc',
},
],
},
],
tutorial: [
{
type: 'doc',
id: 'main',
},
{
type: 'category',
label: 'Generated',
link: {
type: 'generated-index',
permalink: '/current/generated',
},
items: [
{
type: 'doc',
id: 'doc',
},
],
},
],
links: [
{
type: 'link',
href: 'foo',
label: 'Foo',
},
{
type: 'link',
href: 'bar',
label: 'Bar',
},
],
},
categoryGeneratedIndices: [
{
title: 'Generated',
slug: '/current/generated',
permalink: '/current/generated',
sidebar: 'tutorial',
},
],
versionBanner: 'unreleased',
versionBadge: true,
versionClassName: 'current-cls',
tagsPath: '/current/tags',
contentPath: '',
contentPathLocalized: '',
sidebarFilePath: '',
routePriority: 0.5,
}),
).toMatchSnapshot();
});
});

21
packages/docusaurus-plugin-content-docs/src/__tests__/slug.test.ts
View file

@ -111,6 +111,27 @@ describe('getSlug', () => {
).toBe('/dir with spâce/hey $hello/my dôc');
});
it('throws for invalid routes', () => {
expect(() =>
getSlug({
baseID: 'my dôc',
source: '@site/docs/dir with spâce/hey $hello/doc.md',
sourceDirName: '/dir with spâce/hey $hello',
frontMatterSlug: '//',
}),
).toThrowErrorMatchingInlineSnapshot(`
"We couldn't compute a valid slug for document with ID \\"my dôc\\" in \\"/dir with spâce/hey $hello\\" directory.
The slug we computed looks invalid: //.
Maybe your slug front matter is incorrect or there are special characters in the file path?
By using front matter to set a custom slug, you should be able to fix this error:
---
slug: /my/customDocPath
---
"
`);
});
it('handles current dir', () => {
expect(
getSlug({baseID: 'doc', source: '@site/docs/doc.md', sourceDirName: '.'}),

1332
packages/docusaurus-plugin-content-docs/src/__tests__/versions.test.ts
View file

File diff suppressed because it is too large Load diff

2
packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts
View file

@ -25,7 +25,7 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
hide_table_of_contents: Joi.boolean(),
keywords: Joi.array().items(Joi.string().required()),
image: URISchema,
description: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
description: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
slug: Joi.string(),
sidebar_label: Joi.string(),
sidebar_position: Joi.number(),

26
packages/docusaurus-plugin-content-docs/src/docs.ts
View file

@ -391,6 +391,10 @@ export const isCategoryIndex: CategoryIndexMatcher = ({
return eligibleDocIndexNames.includes(fileName.toLowerCase());
};
/**
* `guides/sidebar/autogenerated.md` ->
* `'autogenerated', '.md', ['sidebar', 'guides']`
*/
export function toCategoryIndexMatcherParam({
source,
sourceDirName,
@ -406,28 +410,6 @@ export function toCategoryIndexMatcherParam({
};
}
/**
* `guides/sidebar/autogenerated.md` ->
* `'autogenerated', '.md', ['sidebar', 'guides']`
*/
export function splitPath(str: string): {
/**
* The list of directories, from lowest level to highest.
* If there's no dir name, directories is ['.']
*/
directories: string[];
/** The file name, without extension */
fileName: string;
/** The extension, with a leading dot */
extension: string;
} {
return {
fileName: path.parse(str).name,
extension: path.parse(str).ext,
directories: path.dirname(str).split(path.sep).reverse(),
};
}
// Return both doc ids
// TODO legacy retro-compatibility due to old versioned sidebars using
// versioned doc ids ("id" should be removed & "versionedId" should be renamed

9
packages/docusaurus-plugin-content-docs/src/globalData.ts
View file

@ -6,7 +6,6 @@
*/
import _ from 'lodash';
import {normalizeUrl} from '@docusaurus/utils';
import type {Sidebars} from './sidebars/types';
import {createSidebarsUtils} from './sidebars/utils';
import type {
@ -20,7 +19,7 @@ import type {
GlobalDoc,
} from '@docusaurus/plugin-content-docs/client';
export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
return {
id: doc.unversionedId,
path: doc.permalink,
@ -28,7 +27,7 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
};
}
export function toGlobalDataGeneratedIndex(
function toGlobalDataGeneratedIndex(
doc: CategoryGeneratedIndexMetadata,
): GlobalDoc {
return {
@ -38,7 +37,7 @@ export function toGlobalDataGeneratedIndex(
};
}
export function toGlobalSidebars(
function toGlobalSidebars(
sidebars: Sidebars,
version: LoadedVersion,
): Record<string, GlobalSidebar> {
@ -52,7 +51,7 @@ export function toGlobalSidebars(
link: {
path:
firstLink.type === 'generated-index'
? normalizeUrl([version.versionPath, firstLink.slug])
? firstLink.permalink
: version.docs.find(
(doc) =>
doc.id === firstLink.id || doc.unversionedId === firstLink.id,

6
packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts vendored
View file

@ -18,8 +18,14 @@ declare module '@docusaurus/plugin-content-docs' {
};
export type CategoryIndexMatcherParam = {
/** The file name, without extension */
fileName: string;
/**
* The list of directories, from lowest level to highest.
* If there's no dir name, directories is ['.']
*/
directories: string[];
/** The extension, with a leading dot */
extension: string;
};
export type CategoryIndexMatcher = (

4
packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/utils.test.ts
View file

@ -111,7 +111,7 @@ describe('createSidebarsUtils', () => {
link: {
type: 'generated-index',
slug: '/s4-category-slug',
permalink: '/s4-category-permalink',
permalink: '/s4-category-slug',
},
items: [
{type: 'doc', id: 'doc8'},
@ -291,7 +291,7 @@ describe('createSidebarsUtils', () => {
});
expect(getFirstLink('sidebar4')).toEqual({
type: 'generated-index',
slug: '/s4-category-slug',
permalink: '/s4-category-slug',
label: 'S4 Category',
});
});

11
packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts
View file

@ -139,6 +139,11 @@ export type SidebarsUtils = {
getCategoryGeneratedIndexNavigation: (
categoryGeneratedIndexPermalink: string,
) => SidebarNavigation;
/**
* This function may return undefined. This is usually a user mistake, because
* it means this sidebar will never be displayed; however, we can still use
* `displayed_sidebar` to make it displayed. Pretty weird but valid use-case
*/
getFirstLink: (sidebarId: string) =>
| {
type: 'doc';
@ -147,7 +152,7 @@ export type SidebarsUtils = {
}
| {
type: 'generated-index';
slug: string;
permalink: string;
label: string;
}
| undefined;
@ -295,7 +300,7 @@ Available document ids are:
}
| {
type: 'generated-index';
slug: string;
permalink: string;
label: string;
}
| undefined {
@ -316,7 +321,7 @@ Available document ids are:
} else if (item.link?.type === 'generated-index') {
return {
type: 'generated-index',
slug: item.link.slug,
permalink: item.link.permalink,
label: item.label,
};
}

7
packages/docusaurus-plugin-content-docs/src/slug.ts
View file

@ -63,12 +63,11 @@ export default function getSlug({
function ensureValidSlug(slug: string): string {
if (!isValidPathname(slug)) {
throw new Error(
`We couldn't compute a valid slug for document with id "${baseID}" in "${sourceDirName}" directory.
`We couldn't compute a valid slug for document with ID "${baseID}" in "${sourceDirName}" directory.
The slug we computed looks invalid: ${slug}.
Maybe your slug front matter is incorrect or you use weird chars in the file path?
By using the slug front matter, you should be able to fix this error, by using the slug of your choice:
Maybe your slug front matter is incorrect or there are special characters in the file path?
By using front matter to set a custom slug, you should be able to fix this error:
Example =>
---
slug: /my/customDocPath
---

5
packages/docusaurus-plugin-content-docs/src/translations.ts
View file

@ -274,10 +274,7 @@ function translateVersion(
translationFiles: Record<string, TranslationFile>,
): LoadedVersion {
const versionTranslations =
translationFiles[getVersionFileName(version.versionName)]?.content;
if (!versionTranslations) {
return version;
}
translationFiles[getVersionFileName(version.versionName)]!.content;
return {
...version,
versionLabel:

4
packages/docusaurus-plugin-content-docs/src/versions.ts
View file

@ -74,9 +74,9 @@ function ensureValidVersionString(version: unknown): asserts version is string {
function ensureValidVersionArray(
versionArray: unknown,
): asserts versionArray is string[] {
if (!(versionArray instanceof Array)) {
if (!Array.isArray(versionArray)) {
throw new Error(
`The versions file should contain an array of versions! Found content: ${JSON.stringify(
`The versions file should contain an array of version names! Found content: ${JSON.stringify(
versionArray,
)}`,
);