#59: Enforce parameter naming conventions (#60)

Co-authored-by: Christoph Kuhnke <github@kuhnke.net>

README.md

@@ -9,28 +9,51 @@ This is the interface definition for Exasol extensions that can be installed by
 
 ## Creating New Extensions
 
+This section describes how to create a new extension.
+
+### Base Extension Types
+
 You have the following options for creating a new extensions:
 
-### Generic Interface
+#### Generic Interface
 
 The generic extension interface is defined in [src/api.ts](src/api.ts). It is the most flexible option but requires implementing all extension methods from scratch.
 
 Example: [row-level-security-lua](https://github.com/exasol/row-level-security-lua/blob/main/extension/src/extension.ts)
 
-### Java `SCRIPT` Base 
+#### Java `SCRIPT` Base 
 
 The base extension interface for Java `SCRIPT` based extension is defined in [src/base/index.ts](src/base/index.ts). It is useful for extensions that only consist of one or multiple Java `SCRIPT` UDFs and don't use instances.
 
 Example: [cloud-storage-extension](https://github.com/exasol/cloud-storage-extension/blob/main/extension/src/extension.ts)
 
-### Java `VIRTUAL SCHEMA` Base
+#### Java `VIRTUAL SCHEMA` Base
 
 The base extension interface for Java `VIRTUAL SCHEMA`s is defined in [src/base-vs/index.ts](src/base-vs/index.ts). It is useful for JDBC or document based Virtual Schemas that are based on Java UDFs.
 
 Examples:
 * JDBC based: [oracle-virtual-schema](https://github.com/exasol/oracle-virtual-schema/blob/main/extension/src/extension.ts)
 * Document based: [s3-document-files-virtual-schema](https://github.com/exasol/s3-document-files-virtual-schema/blob/main/extension/src/extension.ts)
 
+## Testing Extensions
+
+Create unit tests for new extensions with Jest. In your test call the function `testJavaVirtualSchemaBaseExtension()` to also run shared unit tests:
+
+```ts
+import { testJavaVirtualSchemaBaseExtension } from '@exasol/extension-manager-interface/dist/base-vs-test/vsTestBase';
+import { createExtension } from "./extension";
+
+// ...
+
+testJavaVirtualSchemaBaseExtension(createExtension);
+```
+
+These shared tests verify the following criteria:
+
+* Parameter IDs don't contain a dot `.`
+* Parameter IDs are unique
+* The extension contains at least one version
+
 ## Additional Information
 
 * [Changelog](doc/changes/changelog.md)

doc/changes/changes_0.4.3.md

@@ -1,4 +1,4 @@
-# Extension Manager Interface 0.4.3, released 2024-05-10
+# Extension Manager Interface 0.4.3, released 2024-05-27
 
 Code name: Improve virtual schema name parameter
 
@@ -8,13 +8,27 @@ This release improves name and regular expression for the virtual schema name pa
 
 This release also reduces code duplication by generating `version.ts` containing the version number from `package.json`.
 
+The release enforces naming conventions for extension parameters. To avoid issues with form IDs in Angular applications, parameter IDs must not contain a dot `.`. To verify that extensions conform to this and other conventions, please call the following function in the extension test:
+
+```ts
+import { testJavaVirtualSchemaBaseExtension } from '@exasol/extension-manager-interface/dist/base-vs-test/vsTestBase';
+import { createExtension } from "./extension";
+
+// ...
+
+testJavaVirtualSchemaBaseExtension(createExtension);
+```
+
+See the [readme](../../README.md#testing-extensions) for details.
+
 ## Bugfixes
 
 * #56: Restricted pattern for parameter  `virtual schema name`
 
 ## Refactoring
 
 * #36: Generated API version from `package.json`
+* #59: Enforced naming conventions for parameter IDs
 
 ## Dependency Updates
 

src/base-vs-test/vsTestBase.test.ts

@@ -0,0 +1,38 @@
+import { ExasolExtension } from "../api";
+import { JavaVirtualSchemaBaseExtension, convertVirtualSchemaBaseExtension, createJsonConnectionDefinition, createVirtualSchemaBuilder } from "../base-vs";
+import { successResult } from "../base/common";
+import { testJavaVirtualSchemaBaseExtension } from "./vsTestBase";
+
+
+
+function emptyBaseVsExtension(): JavaVirtualSchemaBaseExtension {
+    const adapterName = "vs-adapter-script-name"
+    return {
+        name: "testing-base-extension",
+        version: "v0",
+        category: "test-category",
+        description: "Testing base extension",
+        files: [{
+            name: "test-ext.jar",
+            size: 12345
+        }],
+        scripts: [{ name: adapterName, type: "SCALAR", parameters: "...", emitParameters: "...", scriptClass: "com.exasol.TestingAdapter" }],
+        scriptVersionExtractor: () => successResult("dummy version"),
+        virtualSchemaAdapterScript: adapterName,
+        builder: createVirtualSchemaBuilder({
+            connectionNameProperty: "CONNECTION_NAME",
+            virtualSchemaParameters: [
+                { id: "VS_Required", name: "n1", type: "string", required: true },
+                { id: "VS_Optional", name: "n2", type: "string", required: false }],
+            connectionDefinition: createJsonConnectionDefinition([
+                { id: "connRequired", name: "n1", type: "string", required: true },
+                { id: "connOptional", name: "n2", type: "string", required: false }])
+        })
+    }
+}
+
+function createExtension(): ExasolExtension {
+    return convertVirtualSchemaBaseExtension(emptyBaseVsExtension());
+}
+
+testJavaVirtualSchemaBaseExtension(createExtension);

src/base-vs-test/vsTestBase.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from '@jest/globals';
+import { ExasolExtension } from '../api';
+import { createMockContext } from '../base/test-utils';
+
+/**
+ * This function runs shared tests for a virtual schema extension.
+ * 
+ * Call this function in your test file to test your virtual schema extension.
+ * It will assert basic properties of your extension, e.g. having an ID, names
+ * of parameters satisfy conform to the naming conventions, etc.  See the
+ * descriptions of the contained test cases for details.
+ * @param extensionProvider factory for the extension to test
+ */
+export function testJavaVirtualSchemaBaseExtension(extensionProvider: () => ExasolExtension) {
+    const extension = extensionProvider();
+    describe(`extension ${extension.name} versions`, () => {
+        it("has at least one version", () => {
+            expect(extension.installableVersions.length).toBeGreaterThan(0);
+        });
+    });
+    describe(`extension ${extension.name} parameters`, () => {
+        const parameters = extension.getInstanceParameters(createMockContext(), extension.installableVersions[0].name)
+        it("has at least one parameter", () => {
+            expect(parameters.length).toBeGreaterThan(0);
+        });
+        it("contains virtual schema name", () => {
+            expect(parameters.some(p => p.id === "baseVirtualSchemaName")).toBe(true);
+        });
+        it("have a unique ID", () => {
+            const ids = parameters.map(p => p.id);
+            expect(new Set(ids).size).toBe(ids.length);
+        });
+        for (const param of parameters) {
+            it(`parameter '${param.id}' conforms to naming conventions`, () => {
+                expect(param.id).not.toContain(".");
+            });
+        }
+    });
+}

src/base-vs/getInstanceParameters.test.ts

@@ -24,7 +24,7 @@ describe("getInstanceParameters", () => {
             .toStrictEqual([
                 {
                     description: "Name for the new virtual schema",
-                    id: "base-vs.virtual-schema-name",
+                    id: "baseVirtualSchemaName",
                     name: "Virtual schema name",
                     placeholder: "MY_VIRTUAL_SCHEMA",
                     regex: "[a-zA-Z][a-zA-Z0-9_]*",

src/base-vs/parameters.ts

@@ -1,7 +1,7 @@
 import { Parameter } from "../parameters";
 
 export const PARAM_VIRTUAL_SCHEMA_NAME: Parameter = {
-    id: "base-vs.virtual-schema-name",
+    id: "baseVirtualSchemaName",
     name: "Virtual schema name",
     description: "Name for the new virtual schema",
     type: "string",

src/base-vs/test-vs-utils.ts

@@ -33,5 +33,5 @@ export function param(name: string, value: string): ParameterValue {
 }
 
 export function vsNameParam(vsName: string): ParameterValue {
-    return param("base-vs.virtual-schema-name", vsName)
+    return param("baseVirtualSchemaName", vsName)
 }