@magnit-ce/code-tests 0.0.12 → 0.0.14

package/README.md

@@ -1,89 +1,120 @@
-# magnitce-code-tests
-A custom `HTMLElement` that runs tests in-browser and displays the results. 
+# The `code-tests` Custom Element
+
+## Overview
+A custom HTML element that renders code in a syntax-highlight text block, and the results of that code in a display frame.
+
+|||||
+|-|-|-|-|
+|Package size, **verbose**:|~36kb|Package size, **minified**:|~24kb|
 
-Package size: ~24kb minified, ~36kb verbose.
 
-## Quick Reference
+
+## Quick Start
 ```html
 <code-tests src="tests/library.tests.js" title="Library"></code-tests>
 <script type="module" src="/path/to/code-tests[.min].js"></script>
 ```
 
-## Demos
-https://catapart.github.io/magnitce-code-tests/demo/
-
-## Support
-- Firefox
-- Chrome
-- Edge
-- <s>Safari</s> (Has not been tested; should be supported, based on custom element support)
+## Links
+### Demo:
+https://catapart.github.io/magnitce-code-tests
+### Documentation:
+https://catapart.github.io/magnitce-code-tests/documentation
+### Automated Testing:
+https://catapart.github.io/magnitce-code-tests/test-runner
 
-## Getting Started
- 1. [Install/Reference the library](#referenceinstall)
+## Repo Notes
+This section provides instructions for how to use the repo to develop the library.
 
-### Reference/Install
-#### HTML Import (not required for vanilla js/ts; alternative to import statement)
-```html
-<script type="module" src="/path/to/code-tests[.min].js"></script>
-```
-#### npm
+### Installation
+Install the repo using a package manager:
 ```cmd
-npm install @magnit-ce/code-tests
+npm install
 ```
 
-### Import
-#### Vanilla js/ts
-```js
-import "/path/to/code-tests[.min].js"; // if you didn't reference from a <script>, reference with an import like this
+### Configuration
+#### `tsconfig.json`
+The `tsconfig.json` file is generated by the `vite` dependency and has not been modified by this library. It uses strict linting and defaults to `es` modules, rather than `commonjs` modules. For more information about each of the `tsconfig.json` options, see the [tsconfig documentation](https://www.typescriptlang.org/tsconfig/).
+#### `vite.config`
+The `vite.config` file sets defaults options for the dev, build, and release processes, which allows the code to be packaged as a library (rather than a website) and defines custom inputs and outputs to exclude tests and create both `es` and `umd` modules. It also includes settings that allow for multiple file outputs with well-defined names and selective minification. For more information about configuring `vite`, see the [vite config documentation](https://vite.dev/config/).
+#### `vite.config.tests.ts`
+This specialized `vite.config` file defines custom inputs and outputs that include tests and then are packaged into the `test-runner` directory, rather than built to the `dist` directory.
 
-import { CodeTestsElement, CodeTests, expect[, etc...] } from "/path/to/code-tests[.min].js";
-```
-#### npm
-```js
-import "@magnit-ce/code-tests"; // if you didn't reference from a <script>, reference with an import like this
+### Scripts
+#### `dev`
+Use `vite` to begin a server with Hot Module Replacement, which will automatically reload any time a change in a source file is saved.
+#### `build`
+Use `vite` to transpile the source code into code chunks or library files. Files are output into the `dist` directory by default.
+#### `preview`
+Use `vite` to serve the `dist` directory. Useful for non-library projects, where the `dist` directory will contain an `index.html` file, or other browse-able entry point.
+#### `test:build`
+Use `vite` to transpile all files with a `.tests.[ts|js|tsx|jsx]` extension into the `test-runner` subdirectory. Creates javascript files that can be served to the `<test-runner>` and `<code-tests>` components.
+#### `test`
+Runs the `test:build` script and then serves the library website using `serve`, to prevent module resolution issues that occur when running the `dev` script.
+#### `changeset`
+Runs the `npx @changesets/cli` command to create a new changeset which will prepare the library to be published.
+#### `release`
+Use `vite` to transpile the source code and then use `changesets` to begin the publication procedure for the repo environment (github or gitlab).  
+If this script is run during CI/CD for the `main` branch, the library is published to [npm](https://www.npmjs.com/). If it is run during CI/CD for any other branch, the library is linted and compiled. It is expected that this command will *only* be used by a CI/CD pipeline, and **never** by a library dev. Running the `release` script on a local codebase is not supported.
 
-import { CodeTestsElement, CodeTests, expect[, etc...] } from "@magnit-ce/code-tests";
-```
 
----
----
----
+### Publishing
 
-## Overview
-The `<code-tests>` element is a 
+#### Releasing with `changesets`
+Publishing is handled using the `changesets` library which starts the process by requiring a manual entry into a running version log. Once you have defined a set of changes as a version change, the automated processes can prepare the library to be published on to `npm`. When the automation has prepared the release, it will create a pull request from a new branch containing the release package. The publishing developer will be required to merge that branch into main, using the pull request, in order to publish a new version.
 
-## Hooks
-beforeAll:  
-beforeEach:  
-afterEach:  
-afterAll:  
+The step-by-step process is outline below for both Github and Gitlab:
 
-## Providers
-`export` a constant named `providers` to inject arbitrary objects into test calls
+##### Github Steps
+1. **Run `changeset` command**: `npm run changeset` | `bun run changeset` | `pnpm changesets` | `yarn changesets` | `npx @changesets/cli`
+1. **Log version info**: Add a message that describes the changes in this version
+1. **Check in**: Push changes to repo
+1. **Merge**: Merge branch into `main`
+1.  **Merge Automation Branch**: Await repo automation's creation of a new pull request from a newly created branch. Accept the pull request, merging the branch into main.
 
-## Events
-The `<code-tests>` element dispatches the following events:
-- `start`: 
-- `finish`: 
+After automation completes, the new version will be published to `NPM`.
 
-## Attributes
-The `<code-tests>` element uses the `src` attribute.
-The  `test`, `tests`, `run`, and `path` attributes are aliases of the `src` attribute.
+##### Gitlab Steps
+1. **Run `changeset` command**: `npm run changeset` | `bun run changeset` | `pnpm changesets` | `yarn changesets` | `npx @changesets/cli`
+1. **Log version info**: Add a message that describes the changes in this version
+1. **Check in**: Push changes to repo
+1. **Merge**: Merge branch into `main`
+1.  **Merge Automation Branch**: Await repo automation's creation of a new merge request from a newly created branch. Merge the merge request into main.
 
-The `success` attribute is assigned to `true` or `false` when tests have finished.
+After automation completes, the new version will be published to `NPM`.
 
-## Styling
-The `<code-tests>` element can be styled with CSS, normally, but it also makes use of the shadowDOM for it's layout and functionality. Each of the elements in the `<code-tests>` element's shadowRoot can be selected for styling, directly, by using the `::part()` selector.
+### Dependencies
+
+#### Library Dependencies
+
+
+#### Development Dependencies
+
+##### [`typescript`](https://www.typescriptlang.org/)
+Typescript provides type checking at dev time which adds compile-time safety to the codebase for a wide range of issues. For more information on Typescript, visit its [website](https://www.typescriptlang.org/).
+
+##### [`@changesets/cli`](https://github.com/changesets/changesets)
+The `changesets` library uses a strict process to handle versioning and publishing which makes the update and deployment of any library to NPM a structured and repeatable series of steps. Versioning is managed by a command-line utility which enforces release notes and semantic versions. Publishing is handled automatically by CI/CD pipelines when code is checked in. The structure allows for automated pipelines to handle linting and testing, while requiring manual directives to invoke action. Versions are not accidentally published, because all code changes that haven't been packaged into a changeset are transparent to the library. As soon as a version is updated (by the library), the CI/CD pipelines will trigger and the library developer will need to merge branches in order to complete the publishing. By enforcing these procedures, `changesets` keeps this library releasing traceable and well-versioned packages.
+
+##### [`vite`](https://vite.dev/)
+Vite is a packaging library that includes a lot of features that make development faster and easier. Packaging and minifying are built in as well as "hot module reload" so that saving any source file will reload the script in the development environment instantly. That is made even better because Vite also dynamically swaps typescript references for javascript references, meaning that a development build can target and debug with the typescript files directly. It is also configurable enough to account for a wide variety of project types.
+
+##### [`vite-plugin-dts`](https://www.npmjs.com/package/vite-plugin-dts)
+This plugin for the `vite` library allows the packaging process to also produce a `.d.ts` file to describe all of the Typescript types exposed by the library. Without that export, other projects that use Typescript would not be able to see the full manifest of exported types.
+
+##### [`@rollup/plugin-terser`](https://www.npmjs.com/package/@rollup/plugin-terser)
+This plugin, which was developed for one of `vite`'s dependencies (`rollup`) but is used in this project by `vite`, provides a type of minification that is not supported by the default library. Using this plugin, the library can be packaged with both unminified and minified code, so that developers who implement the library can debug the code in un-minified files, while still being able to ship a minified version without having to minify it in their own projects.
+
+##### [`@magnit-ce/test-runner`](https://github.com/catapart/magnitce-test-runner)
+This library adds custom HTML elements that allow developers to run simple definitions for automated tests directly in a browser. These elements are used in the `test-runner` directory to provide live automated testing.
+##### [`glob`](https://www.npmjs.com/package/glob)
+`glob` is a low-level library that provides full-featured search capabilities to a command-line input. These search features are used by this library to differentiate between test files and source files within the `vite.config` files.
+
+##### [`@web/dev-server`](https://modern-web.dev/docs/dev-server/overview/)
+This library provides a local server to serve the project directory without module resolution conflicts between `vite` and the `<test-runner>` element. This library is not necessary if `vite` can be configured to stop wrapping import links for specific run modes (like "testing" vs "development"). At this point, no such configuration has been included in this project so the `web/dev-server` library is used as a work-around for that deficiency.
 
-In this example, the `header` part is being selected for styling:
-```css
-code-tests::part(header)
-{
-    /* styling */
-}
-```
 
-## Parts
+# Warning - Non-production package
+This project is being prepared for production, but is not ready to be used as a dependency for anything. There will be breaking changes and unrecoverable states. Do not use until this warning has been removed.
 
-## License
-This library is in the public domain. You do not need permission, nor do you need to provide attribution, in order to use, modify, reproduce, publish, or sell it or any works using it or derived from it.
+When the library reaches the `1.0.0` designation, that will be a production package. From that point, you can use the major version number (`1` in `1.0.0`) to recognize when breaking changes are introduced.

package/dist/code-tests.d.ts

@@ -1,58 +1,172 @@
-declare class TestPromise<T> extends Promise<T> {
-    toBeDefined(valueName?: string): Promise<void>;
-    toBe(value: any, exact?: boolean): Promise<void>;
-    toContainText(value: string): Promise<void>;
-    toHaveAttribute(value: string): Promise<void>;
-}
-declare class CodeTests {
-    #private;
-    static timeoutMS: number;
-    static expect<T>(value: T): TestPromise<T>;
-    static expectSync<T>(value: T): TestPromise<T>;
-    static expectBefore<T>(value: T): TestPromise<T>;
-    static prompt(host: CodeTestsElement, parent: HTMLElement, message: string, options?: PromptOptions): Promise<boolean>;
-    static createElementFromTemplate(target: string | HTMLTemplateElement, parent?: HTMLElement): HTMLElement;
-}
-declare function expect(value: any): TestPromise<any>;
-type PromptOptions = {
-    acceptLabel?: string;
-    rejectLabel?: string;
-    onAccept?: () => void;
-    onReject?: () => void;
-};
-declare function prompt(host: CodeTestsElement, parent: HTMLElement, message: string, options?: PromptOptions): Promise<boolean>;
-
-type CodeTestsProperties = {};
-declare enum HookType {
-    BeforeAll = "beforeall",
-    AfterAll = "afterall",
-    BeforeEach = "beforeeach",
-    AfterEach = "aftereach",
-    RequiredBeforeAny = "requiredbeforeany",
-    RequiredAfterAny = "requiredafterany"
-}
-declare enum CodeTestEventType {
-    BeforeAll = "beforeall",
-    AfterAll = "afterall",
-    BeforeTest = "beforetest",
-    AfterTest = "aftertest",
-    Cancel = "cancel"
-}
-declare class CodeTestsElement extends HTMLElement {
-    #private;
-    componentParts: Map<string, HTMLElement>;
-    getElement<T extends HTMLElement = HTMLElement>(id: string): T;
-    findElement<T extends HTMLElement = HTMLElement>(id: string): T;
-    constructor();
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    loadTests(testsPath?: string): Promise<void>;
-    isCanceled: boolean;
-    cancel(): void;
-    runTests(): Promise<void>;
-    static create(properties: CodeTestsProperties): HTMLElement;
-    static observedAttributes: string[];
-    attributeChangedCallback(attributeName: string, oldValue: string, newValue: string): void;
-}
-
-export { CodeTestEventType, CodeTests, CodeTestsElement, type CodeTestsProperties, HookType, expect, prompt };
+export declare class CodeTestElement extends HTMLElement {
+    #private;
+    state: CodeTestState;
+    setState(state: CodeTestState): void;
+    setStateProperties(state: Partial<CodeTestState>): void;
+    setTestStateProperties(key: keyof CodeTestState, state: Partial<TestState>): void;
+    findElement<T extends HTMLElement = HTMLElement>(query: string): T;
+    findElements<T extends HTMLElement = HTMLElement>(query: string): T[];
+    isRunning(): boolean;
+    hasRun(): boolean;
+    resultCategory(): TestResultCategory | undefined;
+    connectedCallback(): void;
+    enable(): void;
+    disable(): void;
+    runTest(contextManager: ContextManager, testContext: TestContext): Promise<void>;
+    reset(): void;
+    getMessageElement(): HTMLElement;
+    static observedAttributes: string[];
+    attributeChangedCallback(attributeName: string, _oldValue: string, newValue: string): void;
+}
+
+export declare const CodeTestEvent: {
+    BeforeAll: string;
+    AfterAll: string;
+    BeforeTest: string;
+    AfterTest: string;
+    BeforeHook: string;
+    AfterHook: string;
+    Cancel: string;
+    Context: string;
+    Reset: string;
+};
+
+export declare class CodeTestsElement extends HTMLElement {
+    #private;
+    state: CodeTestsState;
+    setState(state: CodeTestsState): void;
+    setStateProperties(state: Partial<CodeTestsState>): void;
+    setTestStateProperties(key: keyof CodeTestsState, state: Partial<TestState>): void;
+    findElement<T extends HTMLElement = HTMLElement>(query: string): T;
+    findElements<T extends HTMLElement = HTMLElement>(query: string): Array<T>;
+    getIsRunning(): boolean;
+    getResultCategory(): "none" | "success" | "fail";
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    collectTestResults(): GroupTestResults;
+    runTests(): Promise<void>;
+    reloadTests(): Promise<void>;
+    reset(): Promise<void>;
+    cancel(): void;
+    static observedAttributes: string[];
+    attributeChangedCallback(attributeName: string, _oldValue: string, newValue: string): void;
+}
+
+export declare type CodeTestsState = {
+    isCanceled: boolean;
+    beforeAllState?: TestState;
+    afterAllState?: TestState;
+    beforeEachState?: TestState;
+    afterEachState?: TestState;
+    requiredBeforeAnyState?: TestState;
+    requiredAfterAnyState?: TestState;
+    resetHook?: Test;
+    contextHook?: Test;
+};
+
+declare type CodeTestState = {
+    testId: string;
+    description: string;
+    isDisabled: boolean;
+    testState?: TestState;
+    beforeEachState?: TestResultState;
+    afterEachState?: TestResultState;
+};
+
+declare class ContextManager {
+    #private;
+    codeTestsElement: CodeTestsElement;
+    constructor(parent: CodeTestsElement);
+    loadTests(path?: string): Promise<void>;
+    shouldContinueRunningTests: boolean;
+    runTests(tests: CodeTestElement[]): Promise<void>;
+    runTest(test: CodeTestElement | undefined, inLoop: boolean, testContext?: TestContext): Promise<void>;
+    runHook(testStateName: keyof Pick<CodeTestsState, 'requiredBeforeAnyState' | 'requiredAfterAnyState' | 'beforeEachState' | 'afterEachState' | 'beforeAllState' | 'afterAllState'>, test: CodeTestElement | undefined, testContext: TestContext): Promise<string | void | HTMLElement | TestResult | typeof NOTESTDEFINED>;
+    parseTestResult(result: TestResultType | typeof NOTESTDEFINED, finishedTest: boolean, error?: Error): {
+        result: string | HTMLElement;
+        resultCategory: TestResultCategory;
+    };
+    createTestContext(testElement?: CodeTestElement): Promise<TestContext>;
+}
+
+export declare function createElementFromTemplate(target: string | HTMLTemplateElement, parent?: HTMLElement): HTMLElement;
+
+export declare function expect<T>(value: T): TestPromise<T>;
+
+declare type GroupTestResults = {
+    totalTests: number;
+    totalPassed: number;
+    totalPercentage: number;
+    duration: number;
+};
+
+export declare const Hook: {
+    readonly BeforeAll: "beforeall";
+    readonly AfterAll: "afterall";
+    readonly BeforeEach: "beforeeach";
+    readonly AfterEach: "aftereach";
+    readonly RequiredBeforeAny: "requiredbeforeany";
+    readonly RequiredAfterAny: "requiredafterany";
+    readonly Reset: "reset";
+    readonly Context: "context";
+};
+
+export declare type HookType = typeof Hook[keyof typeof Hook];
+
+declare const NOTESTDEFINED: unique symbol;
+
+declare function prompt_2(host: CodeTestElement, parentElement: HTMLElement, message: string, options?: PromptOptions): Promise<boolean>;
+export { prompt_2 as prompt }
+
+export declare type PromptOptions = {
+    template?: HTMLTemplateElement;
+    acceptLabel?: string;
+    rejectLabel?: string;
+    onAccept?: () => void;
+    onReject?: () => void;
+};
+
+declare type Test = <T extends TestResultType>(context: TestContext) => T | Promise<T>;
+
+declare type TestContext = {
+    codeTestsElement: CodeTestsElement;
+    testElement?: CodeTestElement;
+    messageElement?: HTMLElement;
+    detail: any;
+};
+
+export declare class TestPromise<T> extends Promise<T> {
+    toBeDefined(valueName?: string): Promise<void>;
+    toBe(value: any, exact?: boolean): Promise<void>;
+    toContainText(value: string): Promise<false | {
+        success: boolean;
+        index: number;
+    }>;
+    toHaveAttribute(value: string): Promise<void>;
+}
+
+declare type TestResult = {
+    success: boolean;
+    expected?: any;
+    value: string | HTMLElement;
+    data?: any;
+};
+
+declare type TestResultCategory = 'none' | 'success' | 'fail';
+
+declare type TestResultState = {
+    hasRun: boolean;
+    isRunning: boolean;
+    resultCategory: TestResultCategory;
+    resultContent: string | boolean | number | HTMLElement;
+    duration: number;
+};
+
+declare type TestResultType = void | undefined | string | TestResult | HTMLElement;
+
+declare type TestState = TestResultState & {
+    test: Test;
+};
+
+export { }