add unit tests

jsteuer

2019-12-17 4b91478dd762881f81300bbcbb2edc6fcabc536b

add unit tests

 .gitignore

@@ -1,3 +1,4 @@
docs/
node_modules/

.nyc_output/
coverage/

 CHANGELOG.md

@@ -11,11 +11,12 @@



## [1.2.0] - 2019-12-16
## [1.2.0] - 2019-12-17

### Added
-   Beispiele hinzugefügt
-   Hilfsfunktion: `contextFileToExerciseFile` 
-   Unit Tests
### Changed
-   Hilfsfunktionen sind nun im Namensraum `Helpers` untergebracht
### Fixed

 README.md

@@ -283,6 +283,8 @@
    │   └── ...
    ├── media                       // Grafiken
    │   └── ...
    ├── test                        // Unit Tests
    │   └── ...
    ├── src                         // Hilfsfunktionen für Werkzeugentwickler
    │   ├── index.ts                // Einstiegspunkt
    │   └── ...
@@ -293,11 +295,13 @@
    └── tsconfig.json


### Dokumentation erzeugen

#### Dokumentation erzeugen

    npm install && npm run build

### Release einer neuen Version

#### Release einer neuen Version
- Version der API in der `package.json` eintragen
- Beispiele aktualisieren
- Release Tag setzen `git tag -a VERSION -m '...'` und pushen

 package-lock.json

Diff too large

 package.json

@@ -7,14 +7,51 @@
    "example": "examples"
  },
  "devDependencies": {
    "ava": "^2.4.0",
    "nyc": "^14.1.1",
    "rimraf": "^3.0.0",
    "ts-node": "^8.5.4",
    "typedoc": "^0.15.5"
  },
  "scripts": {
    "clean": "rimraf dist/ && rimraf docs/",
    "test": "nyc ava",
    "build": "npm run clean  && npm run build-docs",
    "build-docs": "typedoc mathcoach-api.d.ts src/ --out docs/ --mode file --hideGenerator --theme minimal --includeDeclarations --excludeExternals --media ./media"
  },
  "author": "jsteuer",
  "license": ""
  "license": "",
  "ava": {
    "compileEnhancements": false,
    "extensions": [
      "ts"
    ],
    "require": [
      "ts-node/register"
    ]
  },
  "nyc": {
    "include": [
      "src/**/*.ts",
      "src/**/*.tsx"
    ],
    "exclude": [
      "**/*.d.ts"
    ],
    "extension": [
      ".ts",
      ".tsx"
    ],
    "require": [
      "ts-node/register"
    ],
    "reporter": [
      "text-summary",
      "lcov",
      "html"
    ],
    "sourceMap": true,
    "instrument": true,
    "all": true
  }
}

 src/Helpers.ts

@@ -1,18 +1,17 @@
/// <reference path="../mathcoach-api.d.ts"/>


/**
 * Hilfsfunktionen für Werkzeug-Entwickler. Diese werden nicht durch die `ide-lib.js` 
 * ausgeliefert!
 */
export namespace Helpers {

    /**
     * Bildet die MathCoach API nach, sodass diese auch Offline (ohne IDE) 
     * verfügbar ist.
     * 
     * Das Dateisystem wird durch den LocalStorage des Browsers implementiert.
     * Einige Features der IDE (beispielsweise der Navigator) sind nicht verfügbar 
     * und führen keine Aktionen durch. Alle Aktionen werden in der Browser-Console
     * geloggt.
     * verfügbar ist. Aktuell wird eine Implementierung auf Basis des LocalStorage
     * verwendet. Funktionen wie der Navigator sind nicht verfügbar. Alle API Aufrufe
     * werden in der Browser-Console geloggt.
     * 
     * **Hinweis**: Wenn die echte MathCoach-API der IDE verfügbar ist, hat der Aufruf 
     * dieser Funktion keinen Seiteneffekt.
@@ -21,7 +20,7 @@
     * 
     *      import { Helpers } from "@mathcoach/ide-api";
     *      Helpers.enableOfflineUsageIfNecessary();
     * 
     *      MC.isReady() // use the api
     * 
     * @param contextFileExtension Datei-Erweiterung der Kontext-Datei (Das Werkzeug soll 
     * jedoch unabhängig von der Endung arbeiten können)
@@ -29,11 +28,34 @@
     * wurde, andernfalls `false`
     */
    export function enableOfflineUsageIfNecessary(contextFileExtension: string = "dummy.json"): boolean {
        if (typeof MC === "undefined") {
            console.warn("you are offline - offline api is used");
            const WINDOW = (typeof window === "undefined") ? {} as any : window;
            WINDOW.MC = createStorageBasedApi(contextFileExtension);
            return true;
        } else {
            return false;
        }
    }

    /**
     * Implementierung der MathCoach IDE API zu Testzwecken.
     * 
     * Das Dateisystem wird durch den LocalStorage des Browsers (oder InMemory) implementiert.
     * Einige Features der IDE (beispielsweise der Navigator) sind nicht verfügbar 
     * und führen keine Aktionen durch. Alle Aktionen werden in der Browser-Console
     * geloggt.
     * 
     * Anwendungsbeispiel
     * 
     *      const MC = new LocalStorageBasedApi();
     *      const contextFile = await MC.ide.getContextFile() // use the api
     */
    export function createStorageBasedApi(contextFileExtension: string = "dummy.json"): MathCoach.Api {
        const fileIdentifier = (file: MathCoach.File) => `mock-file://${file.owner}@${file.part}/${file.path}`;
        const traceMethod = (method: string, args?: any[]) => console.log(["[MC MOCK API]", " ", method, "(", (args ? args : [""]).join(","), ")"].join(""));

        class MockAPI implements MathCoach.Api {
        let storage: Storage = (typeof localStorage === "undefined") ? new InMemoryStorage() : localStorage;
        class LocalStorageBasedApi implements MathCoach.Api {

            public ide: MathCoach.IdeApi = {
                async getContextFile(): Promise<MathCoach.File> {
@@ -51,11 +73,11 @@
                fs: {
                    async readFile(file: MathCoach.File) {
                        traceMethod("MC.ide.fs.readFile", [JSON.stringify(file)]);
                        return localStorage.getItem(fileIdentifier(file)) || "";
                        return storage.getItem(fileIdentifier(file)) || "";
                    },
                    async writeFile(file: MathCoach.File, text: string) {
                        traceMethod("MC.ide.fs.writeFile", [JSON.stringify(file), JSON.stringify(`...${text.length} chars...`)]);
                        return localStorage.setItem(fileIdentifier(file), text);
                        return storage.setItem(fileIdentifier(file), text);
                    }
                },
                navigator: {
@@ -68,20 +90,27 @@
                }
            };
            public async isReady(): Promise<boolean> {
                traceMethod("MC.isReady()");
                traceMethod("MC.isReady");
                return true;
            }
        }
        if (typeof MC === "undefined") {
            console.warn("you are offline - offline api is used");
            (window as any).MC = new MockAPI(); // fake the MathCoach-API
            return true;
        } else {
            return false;
        }
        return new LocalStorageBasedApi();
    }


    /**
     * Type Guard, der prüft, ob es sich um eine gültige `MathCoach.File`-Referenz handelt.
     * 
     * @param maybeFile Ein beliebiges Objekt, das geprüft werden soll
     */
    export function isFile(maybeFile: any): maybeFile is MathCoach.File {
        return (maybeFile ? true : false)
            && (maybeFile.owner ? true : false) && (typeof maybeFile.owner === "string")
            && (maybeFile.part ? true : false) && (typeof maybeFile.part === "string")
            && (maybeFile.part === "vfs" || maybeFile.part === "www")
            && (maybeFile.path ? true : false) && (typeof maybeFile.path === "string")
            && (maybeFile.path.indexOf("/") === 0)
    }


    /**
@@ -101,29 +130,47 @@
     *      const exerciseFile: MathCoach.File = Helpers.contextFileToExerciseFile(contextFile);
     */
    export function contextFileToExerciseFile(contextFile: MathCoach.File): MathCoach.File {
        if (contextFile) {
            if (!contextFile.owner || !(typeof contextFile.owner === "string") || !(contextFile.owner.trim() === "")) {
                throw new Error("Context file has no valid 'owner' property.");
            }
            if (!contextFile.part || !(typeof contextFile.part === "string")) {
                if (contextFile.part !== "vfs" && contextFile.part !== "www") {
                    throw new Error("Context file has no valid 'part' property. Allowed values are 'vfs' and 'www'.");
                }
            }
            if (!contextFile.path || !(typeof contextFile.path === "string") || !(contextFile.owner.trim().startsWith("/"))) {
                throw new Error("Context file has no valid 'path' property.");
            }
        } else {
            throw new Error("No context file object given.")
        }
        let file: MathCoach.File = {
        if (isFile(contextFile)) {
            let exerciseFile: MathCoach.File = {
            part: contextFile.part,
            owner: contextFile.owner,
            path: contextFile.path.split(".")[0] + ".groovy"
        };
        return file;
            return exerciseFile;
        } else {
            throw new Error("no valid file reference given, expected object like {owner:'demo', part:'vfs'|'www', path: '/...'}")
        }
    }

    /**
     * Storage auf Basis einer Map. Kann z.B. bei Unit-Tests verwendet
     * werden, beid denen der LocalStorage nicht verfügbar ist.
     */
    class InMemoryStorage implements Storage {

        private readonly items: Map<string, string> = new Map();

        get length(): number {
            return this.items.size;
        }
        clear(): void {
            this.items.clear();
        }
        getItem(key: string): string | null {
            const value = this.items.get(key);
            return value ? value : null;
        }
        key(index: number): string | null {
            throw new Error("FakeStorage: key function is not implemented now");
        }
        removeItem(key: string): void {
            this.items.delete(key);
        }
        setItem(key: string, value: string): void {
            this.items.set(key, value);
        }

}

}


 test/Helpers.spec.ts

New file
@@ -0,0 +1,104 @@
import test from "ava";

import { Helpers } from "../src/Helpers";

test("Helpers.contextFileToExerciseFile works as expected", t => {
    t.deepEqual(
        Helpers.contextFileToExerciseFile({ owner: "demo", part: "vfs", path: "/a/b/aufgabe.tool.json" }),
        { owner: "demo", part: "vfs", path: "/a/b/aufgabe.groovy" } as MathCoach.File
    );
    t.deepEqual(
        Helpers.contextFileToExerciseFile({ owner: "demo", part: "vfs", path: "/a/b/aufgabe.json" }),
        { owner: "demo", part: "vfs", path: "/a/b/aufgabe.groovy" } as MathCoach.File
    );
    t.deepEqual(
        Helpers.contextFileToExerciseFile({ owner: "demo", part: "vfs", path: "/aufgabe.tool.json" }),
        { owner: "demo", part: "vfs", path: "/aufgabe.groovy" } as MathCoach.File
    );
    t.deepEqual(
        Helpers.contextFileToExerciseFile({ owner: "demo", part: "vfs", path: "/aufgabe.json" }),
        { owner: "demo", part: "vfs", path: "/aufgabe.groovy" } as MathCoach.File
    );
})

test("Helpers.contextFileToExerciseFile check params", t => {
    const expectedErrorMessage = "no valid file reference given, expected object like {owner:'demo', part:'vfs'|'www', path: '/...'}"
    t.throws(() => Helpers.contextFileToExerciseFile(null as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile("null" as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: 1, part: 2, path: 3 } as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: "", part: "vfs", path: "/aufgabe.tool.json" } as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: "demo", part: "xxx", path: "/aufgabe.tool.json" } as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: "demo", part: "vfs", path: "notAbsolute.tool.json" } as any), expectedErrorMessage);
})

test("Helpers.isFile", t => {
    t.true(Helpers.isFile({ owner: "demo1", part: "vfs", path: "/aufgabe.json" }))
    t.true(Helpers.isFile({ owner: "demo2", part: "www", path: "/b/aufgabe.json" }))
    t.true(Helpers.isFile({ owner: "demo3", part: "vfs", path: "/" }))

    t.false(Helpers.isFile(undefined))
    t.false(Helpers.isFile({}))
    t.false(Helpers.isFile("test"))

    t.false(Helpers.isFile({ owner: "demo", part: "xxx", path: "/aufgabe.json" })) // bad part
    t.false(Helpers.isFile({ owner: "demo", part: 42, path: "/aufgabe.json" })) // bad part
    t.false(Helpers.isFile({ owner: "demo", path: "/aufgabe.json" })) // bad part


    t.false(Helpers.isFile({ owner: "demo", part: "www", path: "noAbsolutePath.json" })) // bad path
    t.false(Helpers.isFile({ owner: "demo", part: "www", path: "" })) // bad path
    t.false(Helpers.isFile({ owner: "demo", part: "www", path: 42 })) // bad path
    t.false(Helpers.isFile({ owner: "demo", part: "www" })) // bad path

    t.false(Helpers.isFile({ owner: undefined, part: "vfs", path: "/" })) // bad owner
    t.false(Helpers.isFile({ owner: 42, part: "vfs", path: "/" })) // bad owner
    t.false(Helpers.isFile({ part: "vfs", path: "/" })) // bad owner
})


test("Helpers.createLocalStorageBasedApi() MC.isReady", async t => {
    const MC = Helpers.createStorageBasedApi();
    t.true(await MC.isReady());
})

test("Helpers.createLocalStorageBasedApi() MC.ide.getContextFile", async t => {
    const MC = Helpers.createStorageBasedApi();
    const contextFile = await MC.ide.getContextFile()
    t.true(Helpers.isFile(contextFile));
    t.is(contextFile.owner, "jdoe");
    t.is(contextFile.part, "vfs");
    t.is(contextFile.path, "/file.dummy.json");
})

test("Helpers.createLocalStorageBasedApi() MC.ide.getUserName", async t => {
    const MC = Helpers.createStorageBasedApi();
    t.is(await MC.ide.getUserName(), "jdoe");
})

test("Helpers.createLocalStorageBasedApi() MC.ide.fs readFile+writeFile", async t => {
    const MC = Helpers.createStorageBasedApi();
    const contextFile = await MC.ide.getContextFile();
    const exerciseFile = Helpers.contextFileToExerciseFile(contextFile);

    t.is(await MC.ide.fs.readFile(contextFile), "");
    t.is(await MC.ide.fs.readFile(exerciseFile), "");

    await MC.ide.fs.writeFile(contextFile, "123");
    await MC.ide.fs.writeFile(exerciseFile, "456");

    t.is(await MC.ide.fs.readFile(contextFile), "123");
    t.is(await MC.ide.fs.readFile(exerciseFile), "456");
})



test("Helpers.createLocalStorageBasedApi() MC.ide.navigator", async t => {
    const MC = Helpers.createStorageBasedApi();
    const contextFile = await MC.ide.getContextFile();
    const exerciseFile = Helpers.contextFileToExerciseFile(contextFile);

    MC.ide.navigator.navigateTo("www.google.de", true);
    MC.ide.navigator.navigateToExercise(exerciseFile, true);

    t.pass();
})

 tsconfig.json

@@ -4,9 +4,10 @@
    "target": "es5",
    "declaration": true,
    "outDir": "./dist",
    "lib": ["DOM","ES2016"]
  },
  "include": [
    "src/**/*"
  ]
    "lib": [
      "DOM",
      "ES2016"
    ],
    "strict": true
  } 
}