chore(typedoc-plugin-appium): reorganize the tests
many of these were actually E2E tests (and slow)
MODIFY
packages/typedoc-plugin-appium/lib/converter/types.ts
packages/typedoc-plugin-appium/lib/converter/types.ts
@@ -12,7 +12,12 @@ import {
TupleType,
TypeOperatorType,
} from 'typedoc';
-import {AllowedHttpMethod, ParentReflection} from '../model';
+import {
+ AllowedHttpMethod,
+ AppiumPluginReflectionKind,
+ CommandReflection,
+ ParentReflection,
+} from '../model';
import {NAME_EXTERNAL_DRIVER, NAME_TYPES_MODULE} from './builtin-external-driver';
import {NAME_BUILTIN_COMMAND_MODULE, NAME_METHOD_MAP} from './builtin-method-map';
import {NAME_NEW_METHOD_MAP, NAME_EXECUTE_METHOD_MAP, NAME_PARAMS} from './external';
@@ -21,7 +26,7 @@ type WithName<S extends string, R> = R & {
name: S;
};
-type WithKind<K extends ReflectionKind, R> = R & {kind: K};
+type WithKind<K extends ReflectionKind | AppiumPluginReflectionKind, R> = R & {kind: K};
/**
* Utility to narrow a declaration reflection to a specific `SomeType`
@@ -272,3 +277,11 @@ export type NonEmptyArray<T> = [T, ...T[]];
export type CallSignatureReflectionWithArity = CallSignatureReflection & {
parameters: NonEmptyArray<ParameterReflection>;
};
+
+/**
+ * Can be used to narrow a {@linkcode CommandReflection} to one representing an execute method.
+ */
+export type ExecuteMethodCommandReflection = CommandReflection & {
+ kind: typeof AppiumPluginReflectionKind.ExecuteMethod;
+ script: string;
+};

MODIFY
packages/typedoc-plugin-appium/package.json
packages/typedoc-plugin-appium/package.json
"build": "cpy lib/theme/resources build",
"clean": "npx rimraf build/lib/theme/resources",
"test": "run-s test:unit",
- "test:e2e": "exit 0",
+ "test:e2e": "mocha --timeout 20s \"test/e2e/**/*.e2e.spec.ts\"",
"test:smoke": "node ./index.js",
- "test:unit": "mocha --no-timeout \"test/unit/**/*.spec.ts\""
+ "test:unit": "mocha --timeout 2s \"test/unit/**/*.spec.ts\""
},
"bugs": {
"url": "https://github.com/appium/appium/issues"

RENAME
packages/typedoc-plugin-appium/test/unit/converter/builtin-external-driver.spec.ts
packages/typedoc-plugin-appium/test/e2e/converter/builtin-external-driver.e2e.spec.ts
RENAME
packages/typedoc-plugin-appium/test/unit/converter/builtin-method-map.spec.ts
packages/typedoc-plugin-appium/test/e2e/converter/builtin-method-map.e2e.spec.ts
ADD
packages/typedoc-plugin-appium/test/e2e/converter/comment.e2e.spec.ts
+import {expect} from 'chai';
+import {
+ KnownMethods,
+ BuiltinExternalDriverConverter,
+ NAME_TYPES_MODULE,
+ deriveComment,
+} from '../../../lib/converter';
+import {initConverter} from '../helpers';
+
+describe('@appium/typedoc-plugin-appium', function () {
+ describe('deriveComment()', function () {
+ let knownMethods: KnownMethods;
+
+ before(async function () {
+ const converter = await initConverter(BuiltinExternalDriverConverter, NAME_TYPES_MODULE);
+ knownMethods = converter.convert();
+ expect(knownMethods.size).to.be.greaterThan(0);
+ expect(knownMethods.get('activateApp')!.comment).to.exist;
+ });
+
+ describe('when not provided a reflection nor `Comment` parameter', function () {
+ it('should derive the comment from KnownMethods', function () {
+ const commentData = deriveComment('activateApp', knownMethods);
+ expect(commentData).to.exist.and.to.have.keys('comment', 'commentSource');
+ });
+ });
+ });
+});

RENAME
packages/typedoc-plugin-appium/test/unit/converter/index.spec.ts
packages/typedoc-plugin-appium/test/e2e/converter/converter.e2e.spec.ts
@@ -12,7 +12,7 @@ import {initAppForPkgs, NAME_FAKE_DRIVER_MODULE} from '../helpers';
const {expect} = chai;
describe('@appium/typedoc-plugin-appium', function () {
- describe('converter', function () {
+ describe('convertCommands()', function () {
let sandbox: SinonSandbox;
beforeEach(function () {
sandbox = createSandbox();

RENAME
packages/typedoc-plugin-appium/test/unit/converter/external.spec.ts
packages/typedoc-plugin-appium/test/e2e/converter/external.e2e.spec.ts
RENAME
packages/typedoc-plugin-appium/test/unit/helpers.ts
packages/typedoc-plugin-appium/test/e2e/helpers.ts
ADD
packages/typedoc-plugin-appium/test/e2e/index.e2e.spec.ts
+import {
+ Application,
+ Context,
+ DeclarationReflection,
+ ProjectReflection,
+ ReflectionKind,
+ TypeDocOptions,
+} from 'typedoc';
+import {convert, ConvertResult, postProcess, PostProcessResult, setup} from '../../lib';
+import {
+ ExecuteMethodCommandReflection,
+ NAME_BUILTIN_COMMAND_MODULE,
+ NAME_TYPES_MODULE,
+} from '../../lib/converter';
+import {AppiumPluginReflectionKind, CommandReflection, ExtensionReflection} from '../../lib/model';
+import {initAppForPkgs, NAME_FAKE_DRIVER_MODULE} from './helpers';
+
+const {expect} = chai;
+describe('@appium/typedoc-plugin-appium', function () {
+ /**
+ * Result of {@linkcode convert}
+ */
+ let resolveBeginCtxPromise: Promise<ConvertResult>;
+
+ /**
+ * Result of {@linkcode postProcess}
+ */
+ let resolveEndCtxPromise: Promise<PostProcessResult>;
+ /**
+ * Whatever {@linkcode Context} we're using to test
+ */
+ let ctx: Context;
+
+ /**
+ * Array of {@linkcode ExtensionReflection} instances as in a {@linkcode ConvertResult}
+ */
+ let extensionReflections!: ExtensionReflection[];
+
+ /**
+ * Creates a new TypeDoc application and/or resets it
+ */
+ function reset({
+ entryPoints = [NAME_TYPES_MODULE, NAME_FAKE_DRIVER_MODULE, NAME_BUILTIN_COMMAND_MODULE],
+ ...opts
+ }: Partial<TypeDocOptions> = {}): Application {
+ return setup(initAppForPkgs({entryPoints, ...opts}));
+ }
+
+ describe('convert()', function () {
+ describe('when "theme" is not "markdown" or "appium"', function () {
+ it('should do nothing', async function () {
+ const app = reset({theme: 'foo'});
+ resolveBeginCtxPromise = convert(app);
+ app.convert();
+ await expect(resolveBeginCtxPromise).to.eventually.not.have.all.keys(
+ 'projectCommands',
+ 'extensionReflections'
+ );
+ });
+ });
+
+ describe('when commands are found in the project', function () {
+ before(async function () {
+ const app = reset();
+ resolveBeginCtxPromise = convert(app);
+ app.convert();
+ const result = await resolveBeginCtxPromise;
+ extensionReflections = result.extensionReflections!;
+ });
+
+ it('should create CommandReflections for each extension', function () {
+ for (const extRefl of extensionReflections) {
+ const cmdRefls = extRefl.getChildrenByKind(AppiumPluginReflectionKind.Command as any);
+ expect(cmdRefls).to.not.be.empty;
+ }
+ });
+ });
+
+ describe('when no commands found in the project', function () {
+ it('should return an object without projectCommands and extensionReflections', async function () {
+ const app = reset({entryPoints: [NAME_TYPES_MODULE]});
+ resolveBeginCtxPromise = convert(app);
+ app.convert();
+ await expect(resolveBeginCtxPromise).to.eventually.not.have.all.keys(
+ 'projectCommands',
+ 'extensionReflections'
+ );
+ });
+ });
+ });
+
+ describe('postProcess()', function () {
+ let project: ProjectReflection;
+ let removed: Set<DeclarationReflection> | undefined;
+
+ describe('when the `outputModules` option is false', function () {
+ before(async function () {
+ const app = reset();
+ app.options.setValue('outputModules', false);
+ resolveBeginCtxPromise = convert(app);
+ resolveEndCtxPromise = postProcess(app);
+ app.convert();
+ [, {ctx, removed}] = await Promise.all([resolveBeginCtxPromise, resolveEndCtxPromise]);
+ ({project} = ctx);
+ });
+
+ it('should mutate the project', function () {
+ const childRefls = project.getChildrenByKind(AppiumPluginReflectionKind.Extension as any);
+ expect(childRefls).to.have.lengthOf(project.children!.length).and.to.not.be.empty;
+ expect(project.getChildrenByKind(ReflectionKind.Module)).to.be.empty;
+ });
+
+ it('should remove DeclarationReflections', function () {
+ expect(removed).not.to.be.empty;
+ });
+ });
+
+ describe('when the `outputModules` option is true', function () {
+ before(async function () {
+ const app = reset();
+ app.options.setValue('outputModules', true);
+ resolveBeginCtxPromise = convert(app);
+ resolveEndCtxPromise = postProcess(app);
+ app.convert();
+ [, {ctx, removed}] = await Promise.all([resolveBeginCtxPromise, resolveEndCtxPromise]);
+ ({project} = ctx);
+ });
+
+ it('should not remove anything from the project', function () {
+ const defaultRefls = project.getChildrenByKind(
+ ~(AppiumPluginReflectionKind.Extension as any)
+ );
+ expect(defaultRefls).to.not.be.empty;
+ const pluginRefls = project.getChildrenByKind(AppiumPluginReflectionKind.Extension as any);
+ expect(pluginRefls).to.not.be.empty;
+ });
+
+ it('should not remove DeclarationReflections', function () {
+ expect(removed).to.be.undefined;
+ });
+ });
+ });
+});

DELETE
packages/typedoc-plugin-appium/test/unit/converter/comment.spec.ts
-import {expect} from 'chai';
-import {
- KnownMethods,
- BuiltinExternalDriverConverter,
- NAME_TYPES_MODULE,
- deriveComment,
-} from '../../../lib/converter';
-import {initConverter} from '../helpers';
-
-describe('@appium/typedoc-plugin-appium', function () {
- describe('comment', function () {
- describe('deriveComment()', function () {
- let knownMethods: KnownMethods;
-
- before(async function () {
- const converter = await initConverter(BuiltinExternalDriverConverter, NAME_TYPES_MODULE);
- knownMethods = converter.convert();
- expect(knownMethods.size).to.be.greaterThan(0);
- expect(knownMethods.get('activateApp')!.comment).to.exist;
- });
-
- describe('when not provided a reflection nor `Comment` parameter', function () {
- it('should derive the comment from KnownMethods', function () {
- const commentData = deriveComment('activateApp', knownMethods);
- expect(commentData).to.exist.and.to.have.keys('comment', 'commentSource');
- });
- });
- });
- });
-});

DELETE
packages/typedoc-plugin-appium/test/unit/converter/plugin.spec.ts
-import {
- Application,
- Context,
- DeclarationReflection,
- ProjectReflection,
- ReflectionKind,
- TypeDocOptions,
-} from 'typedoc';
-import {convert, ConvertResult, postProcess, PostProcessResult, setup} from '../../../lib';
-import {NAME_BUILTIN_COMMAND_MODULE, NAME_TYPES_MODULE} from '../../../lib/converter';
-import {
- AppiumPluginReflectionKind,
- CommandReflection,
- ExtensionReflection,
-} from '../../../lib/model';
-import {initAppForPkgs, NAME_FAKE_DRIVER_MODULE} from '../helpers';
-
-const {expect} = chai;
-describe('@appium/typedoc-plugin-appium', function () {
- describe('plugin', function () {
- /**
- * Result of {@linkcode convert}
- */
- let resolveBeginCtxPromise: Promise<ConvertResult>;
-
- /**
- * Result of {@linkcode postProcess}
- */
- let resolveEndCtxPromise: Promise<PostProcessResult>;
- /**
- * Whatever {@linkcode Context} we're using to test
- */
- let ctx: Context;
-
- /**
- * Array of {@linkcode ExtensionReflection} instances as in a {@linkcode ConvertResult}
- */
- let extensionReflections!: ExtensionReflection[];
-
- /**
- * Creates a new TypeDoc application and/or resets it
- */
- function reset({
- entryPoints = [NAME_TYPES_MODULE, NAME_FAKE_DRIVER_MODULE, NAME_BUILTIN_COMMAND_MODULE],
- ...opts
- }: Partial<TypeDocOptions> = {}): Application {
- const app = initAppForPkgs({entryPoints, ...opts});
- setup(app);
- return app;
- }
-
- describe('convert()', function () {
- describe('when "theme" is not "markdown" or "appium"', function () {
- it('should do nothing', async function () {
- const app = reset({theme: 'foo'});
- resolveBeginCtxPromise = convert(app);
- app.convert();
- await expect(resolveBeginCtxPromise).to.eventually.not.have.all.keys(
- 'projectCommands',
- 'extensionReflections'
- );
- });
- });
-
- describe('when commands are found in the project', function () {
- before(async function () {
- const app = reset();
- resolveBeginCtxPromise = convert(app);
- app.convert();
- const result = await resolveBeginCtxPromise;
- extensionReflections = result.extensionReflections!;
- });
-
- it('should sort commands in ascending order by route', function () {
- for (const cmdsRefl of extensionReflections) {
- let lastRoute = '';
- for (const cmdRefl of cmdsRefl.getChildrenByKind(
- AppiumPluginReflectionKind.Command as any
- ) as CommandReflection[]) {
- if (lastRoute) {
- expect(cmdRefl.route.localeCompare(lastRoute)).to.greaterThanOrEqual(0);
- }
- lastRoute = cmdRefl.route;
- }
- }
- });
-
- it('should sort exec methods in ascending order by script', function () {
- for (const cmdsRefl of extensionReflections) {
- let lastScript: string | undefined = undefined;
- for (const cmdRefl of cmdsRefl.getChildrenByKind(
- AppiumPluginReflectionKind.ExecuteMethod as any
- ) as CommandReflection[]) {
- if (lastScript) {
- expect(cmdRefl.script!.localeCompare(lastScript)).to.greaterThanOrEqual(0);
- }
- lastScript = cmdRefl.script!;
- }
- }
- });
- });
-
- describe('when no commands found in the project', function () {
- it('should return an object without projectCommands and extensionReflections', async function () {
- const app = reset({entryPoints: [NAME_TYPES_MODULE]});
- resolveBeginCtxPromise = convert(app);
- app.convert();
- await expect(resolveBeginCtxPromise).to.eventually.not.have.all.keys(
- 'projectCommands',
- 'extensionReflections'
- );
- });
- });
- });
-
- describe('postProcess()', function () {
- let project: ProjectReflection;
- let removed: Set<DeclarationReflection> | undefined;
-
- describe('when the `outputModules` option is false', function () {
- before(async function () {
- const app = reset();
- app.options.setValue('outputModules', false);
- resolveBeginCtxPromise = convert(app);
- resolveEndCtxPromise = postProcess(app);
- app.convert();
- [, {ctx, removed}] = await Promise.all([resolveBeginCtxPromise, resolveEndCtxPromise]);
- ({project} = ctx);
- });
-
- it('should mutate the project', function () {
- const childRefls = project.getChildrenByKind(AppiumPluginReflectionKind.Extension as any);
- expect(childRefls).to.have.lengthOf(project.children!.length).and.to.not.be.empty;
- expect(project.getChildrenByKind(ReflectionKind.Module)).to.be.empty;
- });
-
- it('should remove DeclarationReflections', function () {
- expect(removed).not.to.be.empty;
- });
- });
-
- describe('when the `outputModules` option is true', function () {
- before(async function () {
- const app = reset();
- app.options.setValue('outputModules', true);
- resolveBeginCtxPromise = convert(app);
- resolveEndCtxPromise = postProcess(app);
- app.convert();
- [, {ctx, removed}] = await Promise.all([resolveBeginCtxPromise, resolveEndCtxPromise]);
- ({project} = ctx);
- });
-
- it('should not remove anything from the project', function () {
- const defaultRefls = project.getChildrenByKind(
- ~(AppiumPluginReflectionKind.Extension as any)
- );
- expect(defaultRefls).to.not.be.empty;
- const pluginRefls = project.getChildrenByKind(
- AppiumPluginReflectionKind.Extension as any
- );
- expect(pluginRefls).to.not.be.empty;
- });
-
- it('should not remove DeclarationReflections', function () {
- expect(removed).to.be.undefined;
- });
- });
- });
- });
-});

chore(typedoc-plugin-appium): reorganize the tests

many of these were actually E2E tests (and slow)