kempo-testing-framework 1.1.0

package/.github/copilot-instructions.md

@@ -0,0 +1,105 @@
+# Code Contribution Guidelines
+
+## Project Structure
+
+ - All code should be in the `src/` directory, with the exception of index.js.
+ - All utility function module files should be in the `src/utils/` directory.
+
+### GUI
+
+All files served by the GUI should be in the `gui/` directory, with the exception of scripts shared with the CLI, custom endpoints, and node_modules like essential.css (which should have custom endpoints).
+
+## Coding Style Guidelines
+
+### Code Organization
+Use multi-line comments to separate code into logical sections. Group related functionality together.
+  - Example: In Lit components, group lifecycle callbacks, event handlers, public methods, utility functions, and rendering logic separately.
+
+```javascript
+/*
+  Lifecycle Callbacks
+*/
+```
+
+### Avoid single-use variables/functions
+Avoid defining a variable or function to only use it once; inline the logic where needed. Some exceptions include:
+  - recursion
+  - scope encapsulation (IIFE)
+  - context changes
+
+### Minimal Comments, Empty Lines, and Spacing
+
+Use minimal comments. Assume readers understand the language. Some exceptions include:
+  - complex logic
+  - anti-patterns
+  - code organization
+
+Do not put random empty lines within code; put them where they make sense for readability, for example:
+  - above and below definitions for functions and classes.
+  - to help break up large sections of logic to be more readable. If there are 100 lines of code with no breaks, it gets hard to read.
+  - above multi-line comments to indicate the comment belongs to the code below
+
+No  empty lines in css.
+
+End each file with an empty line.
+
+End each line with a `;` when possible, even if it is optional.
+
+Avoid unnecessary spacing, for example:
+  - after the word `if`
+  - within parentheses for conditional statements
+
+```javascript
+let count = 1;
+
+const incrementOdd = (n) => {
+  if(n % 2 !== 0){
+    return n++;
+  }
+  return n;
+};
+
+count = incrementOdd(count);
+```
+
+### Prefer Arrow Functions
+Prefer the use of arrow functions when possible, especially for class methods to avoid binding. Use normal functions if needed for preserving the proper context.
+ - For very basic logic, use implicit returns
+ - If there is a single parameter, omit the parentheses.
+```javascript
+const addOne = n => n + 1;
+```
+
+### Module Exports
+  - If a module has only one export, use the "default" export, not a named export.
+    - Do not declare the default export as a const or give it a name; just export the value.
+
+```javascript
+export default (n) => n + 1;
+```
+  - If a module has multiple exports, use named exports and do not use a "default" export.
+
+### Code Reuse
+Create utility functions for shared logic.
+  - If the shared logic is used in a single file, define a utility function in that file.
+  - If the shared logic is used in multiple files, create a utility function module file in `src/utils/`.
+
+### Naming
+Do not prefix identifiers with underscores.
+  - Never use leading underscores (`_`) for variable, property, method, or function names.
+  - Use clear, descriptive names without prefixes.
+  - When true privacy is needed inside classes, prefer native JavaScript private fields (e.g., `#myField`) instead of simulated privacy via underscores.
+
+## Lit Components
+
+### Component Architecture and Communication
+
+- Use methods to cause actions; do not emit events to trigger logic. Events are for notifying that something already happened.
+  - Prefer `el.closest('ktf-test-framework')?.enqueueSuite({...})` over firing an `enqueue` event.
+
+- Wrap dependent GUI components inside a parent `ktf-test-framework` element. Children find it via `closest('ktf-test-framework')` and call its methods. The framework can query its subtree to orchestrate children.
+
+- Avoid `window` globals and global custom events for coordination. If broadcast is needed, scope events to the framework element; reserve window events for global, non-visual concerns (e.g., settings changes).
+
+- Queued status must show the `scheduled` icon. Running may apply `animation="spin"`.
+

package/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Code Contribution Guidelines
+
+## Project Structure
+
+ - All code should be in the `src/` directory, with the exception of index.js.
+ - All utility function module files should be in the `src/utils/` directory.
+
+### GUI
+
+All files served by the GUI should be in the `gui/` directory, with the exception of scripts shared with the CLI, custom endpoints, and node_modules like essential.css (which should have custom endpoints).
+
+## Coding Style Guidelines
+
+### Code Organization
+Use multi-line comments to separate code into logical sections. Group related functionality together.
+  - Example: In Lit components, group lifecycle callbacks, event handlers, public methods, utility functions, and rendering logic separately.
+
+```javascript
+/*
+  Lifecycle Callbacks
+*/
+```
+
+### Avoid single-use variables/functions
+Avoid defining a variable or function to only use it once; inline the logic where needed. Some exceptions include:
+  - recursion
+  - scope encapsulation (IIFE)
+  - context changes
+
+### Minimal Comments, Empty Lines, and Spacing
+
+Use minimal comments. Assume readers understand the language. Some exceptions include:
+  - complex logic
+  - anti-patterns
+  - code organization
+
+Do not put random empty lines within code; put them where they make sense for readability, for example:
+  - above and below definitions for functions and classes.
+  - to help break up large sections of logic to be more readable. If there are 100 lines of code with no breaks, it gets hard to read.
+  - above multi-line comments to indicate the comment belongs to the code below
+
+No  empty lines in css.
+
+End each file with an empty line.
+
+End each line with a `;` when possible, even if it is optional.
+
+Avoid unnecessary spacing, for example:
+  - after the word `if`
+  - within parentheses for conditional statements
+
+```javascript
+let count = 1;
+
+const incrementOdd = (n) => {
+  if(n % 2 !== 0){
+    return n++;
+  }
+  return n;
+};
+
+count = incrementOdd(count);
+```
+
+### Prefer Arrow Functions
+Prefer the use of arrow functions when possible, especially for class methods to avoid binding. Use normal functions if needed for preserving the proper context.
+ - For very basic logic, use implicit returns
+ - If there is a single parameter, omit the parentheses.
+```javascript
+const addOne = n => n + 1;
+```
+
+### Module Exports
+  - If a module has only one export, use the "default" export, not a named export.
+    - Do not declare the default export as a const or give it a name; just export the value.
+
+```javascript
+export default (n) => n + 1;
+```
+  - If a module has multiple exports, use named exports and do not use a "default" export.
+
+### Code Reuse
+Create utility functions for shared logic.
+  - If the shared logic is used in a single file, define a utility function in that file.
+  - If the shared logic is used in multiple files, create a utility function module file in `src/utils/`.
+
+### Naming
+Do not prefix identifiers with underscores.
+  - Never use leading underscores (`_`) for variable, property, method, or function names.
+  - Use clear, descriptive names without prefixes.
+  - When true privacy is needed inside classes, prefer native JavaScript private fields (e.g., `#myField`) instead of simulated privacy via underscores.
+
+## Lit Components
+
+### Component Architecture and Communication
+
+- Prefer direct method calls to trigger behavior. Do not dispatch custom events to make something happen. Use events only to inform that something already happened.
+  - Do: `this.closest('ktf-test-framework').enqueueTest({...});`
+  - Don’t: `this.closest('ktf-test-framework').dispatchEvent(new CustomEvent('enqueue', {...}))` to trigger logic.
+
+- Containment-first design: place orchestrators (e.g., `ktf-test-framework`) as a parent that wraps all dependent components (summary, suites, tests). Children should locate the parent with `closest('ktf-test-framework')` and call its methods.
+  - Parents may query their own subtree (`this.querySelectorAll(...)`) to find children.
+
+- Avoid window globals and window-scoped events for app logic. Scope cross-component events to the containing framework element when possible. Window events are reserved for process-wide concerns (e.g., settings store changes).
+
+- Status and UI mapping: queued status should render the `scheduled` icon; running may use spin animation.
+

package/README.md

@@ -0,0 +1,293 @@
+# Kempo Testing Framework
+
+The Kempo Testing Framework is a simple testing framework built on these principles:
+
+- **Test in the right environment:** Code should be tested in the environment it is written for. Code intended to be ran in the browser is tested in the browser; code intended to be ran in Node is tested in Node. And code intended to be ran in either should be tested in both.
+- **No mocks, no shims:** Test the real thing, not a simulation.
+- **Simplicity:** No custom syntax to learn. Just JavaScript functions and three helpers: `log`, `pass`, and `fail`.
+- **Zero learning curve:** If you know JavaScript, you know how to write tests.
+
+It can be run from a web GUI or from the command line.
+
+This was originally built to test Kempo, but there is nothing Kempo specific about it, it could be used for any JavaScript project.
+
+## Requirements
+
+- Node.js version 14.8.0 or higher is required (for ES modules and top-level await support).
+- Modern browsers for running browser tests.
+
+If you are using an older version of Node.js, please upgrade to a supported version to use Kempo Testing Framework.
+
+## Setup
+
+Install `kempo-testing-framework` as a dependency in your project:
+
+```bash
+npm install kempo-testing-framework --save-dev
+```
+
+## Test Types
+
+Kempo supports two types of tests that can coexist in the same test suite:
+
+### Browser Tests
+Tests that run directly in the browser environment. Best for:
+- DOM manipulation
+- Browser APIs
+- UI components
+- Client-side functionality
+
+### Node Tests  
+Tests that run on the server via API calls. Best for:
+- Server-side logic
+- File system operations
+- Node-specific APIs
+- Pure JavaScript functions
+
+Each type of test (browser / node) should have its own test file, but both will run 
+
+## Test File Naming
+
+Kempo supports three types of test files:
+
+- `[name].browser-test.js` — runs only in the browser
+- `[name].node-test.js` — runs only in Node
+- `[name].test.js` — runs in both environments
+
+If your code is intended to run in both Node and the browser, you should write a single test file named `[name].test.js.`, otherwise use the environment specific file names `[name].browser-test.js` and/or `[name]node-test.js`.
+
+## Writing Tests
+
+### Lifecycle Callbacks
+Test files can export the following optional lifecycle functions:
+
+- **`beforeAll`** - Runs once before all tests (setup)
+- **`afterAll`** - Runs once after all tests (cleanup)  
+- **`beforeEach`** - Runs before each individual test
+- **`afterEach`** - Runs after each individual test
+
+**Note:** All test functions and lifecycle callbacks can be `async` functions if you need to await asynchronous operations.
+
+## Example Test File
+
+`[name].test.js`, `[name].browser-test.js`, or `[name].node-test.js`... they all should look exactly the same.
+
+```javascript
+// Import the thing to test
+import yourModule from '../../src/yourModule.js';
+
+/* Export the optional lifecycle callbacks */
+export const beforeAll = async (log) => {
+  log('Setting up Node test environment...');
+}
+
+export const beforeEach = async (log) => {
+  log('Setting up Node test for each test')
+}
+
+export const beforeEach = async (log) => {
+  log('Cleaning up Node test for each test')
+}
+
+export const afterAll = async (log) => {
+  log('Cleaning up Node test environment...');
+}
+
+/* Export the Tests */
+export default {
+  'should handle basic functionality': async ({pass, fail, log}) => {
+    const expected = 'abc123';
+    const result = yourModule.someFunction();
+    if (result === expected) {
+      log('✓ Basic functionality works');
+      pass('Test passed successfully')
+    } else {
+      fail(`Expected ${expected}, got ${result}`);
+    }
+  },
+  'should validate input parameters': async ({pass, fail, log}) => {
+    try {
+      yourModule.someFunction(null);
+      fail('Should have thrown an error for null input');
+    } catch (error) {
+      log('✓ Properly validates input');
+      pass('Input validation test passed');
+    }
+  }
+};
+```
+
+
+## Running Tests
+
+### CLI (Command-Line Interface)
+Run all tests using npx:
+```bash
+npx kempo-test
+```
+
+Run only the browser tests:
+```bash
+npx kempo-test -b
+```
+
+Run only the node tests:
+```bash
+npx kempo-test -n
+```
+
+### GUI (webpage)
+
+Run the GUI interface:
+```bash
+npx kempo-test --gui
+```
+
+### Using npm Scripts (Optional)
+
+You can add npm scripts to your `package.json` for convenience:
+
+```json
+{
+  "scripts": {
+    "tests": "npx kempo-test",
+    "tests:gui": "npx kempo-test --gui",
+    "tests:browser": "npx kempo-test -b",
+    "tests:node": "npx kempo-test -n"
+  }
+}
+```
+
+Then run with:
+```bash
+npm run tests           # Run all tests
+npm run tests:gui       # Start GUI
+npm run tests:browser   # Run only browser tests
+npm run tests:node      # Run only node tests
+```
+
+**Important:** npm scripts with npx don't reliably pass additional arguments. If you need to use flags like `--show-browser`, `--log-level`, or filters, use `npx kempo-test` directly instead of npm scripts.
+
+## CLI Flags Reference
+
+When running tests via the CLI, you can use various flags to control test execution and output. These flags only affect CLI execution and are ignored when using the GUI (`--gui` flag).
+
+Note: For flags that take values, you can use either a space or equals: `--log-level verbose` or `--log-level=verbose`. Short flags also support equals for value flags: `-l verbose` or `-l=verbose`. Examples below use spaces for clarity.
+
+### Environment Flags
+
+**`-b` or `--browser`**
+- Runs only browser tests (`.browser-test.js` files and `.test.js` files in browser environment)
+- Example: `npx kempo-test -b`
+- Example with filter: `npx kempo-test -b auth`
+
+**`-n` or `--node`**  
+- Runs only Node tests (`.node-test.js` files and `.test.js` files in Node environment)
+- Example: `npx kempo-test -n`
+- Example with filter: `npx kempo-test -n user`
+
+### Log Level Flag
+
+Set the verbosity of output:
+
+**`-l` or `--log-level`**
+- Accepts numeric 0–4 or names: `silent|minimal|normal|verbose|debug` (also `s|m|n|v|d`)
+- Examples:
+  - `npx kempo-test -l debug`
+  - `npx kempo-test --log-level 3`
+  - `npx kempo-test -l n`
+
+### Server Configuration Flags
+
+**`-p` or `--port`**
+- Specify the port for the browser test server (default: 3000)
+- Port must be between 1 and 65535
+- Example: `npx kempo-test -b --port 8080`
+- Example: `npx kempo-test -p 3001`
+
+**`--show-browser` or `-w`**
+- Show the browser window during browser tests (default: headless mode)
+- Useful for debugging browser tests and seeing what's happening
+- Example: `npx kempo-test -b --show-browser`
+- Example: `npx kempo-test -b -w`
+
+**`--delay` or `-d`**
+- Specify a browser pause delay in milliseconds (applies before and after browser tests when the browser window is shown)
+- Example: `npx kempo-test -b --show-browser --delay 2000`
+
+### Combining Flags
+
+You can combine multiple flags for precise control:
+
+```bash
+# Run only browser tests with verbose-like output using log level
+npx kempo-test -b -l verbose auth
+
+# Run only node tests with minimal output
+npx kempo-test -n -l minimal user
+
+# Run all tests silently with a specific filter
+npx kempo-test -l silent payment
+
+# Run browser tests with visible browser window, custom port and delay
+npx kempo-test -b --show-browser --port 8080 --delay 2000
+```
+
+## Running Specific or Filtered Tests
+
+Kempo supports two levels of filtering to help you run only the tests you need:
+
+### File-Level Filtering
+
+You can filter which test files to run by providing a partial filename (substring) as an argument. All test files whose names include the substring will be run. This works for both full and partial names, and matches anywhere in the filename (not just the start).
+
+For example, if you have test files named `auth.browser-test.js`, `auth.node-test.js`, `user-auth.test.js`, and `payment.test.js`:
+
+Run all tests with `auth` in the name (in both environments):
+```bash
+npx kempo-test auth
+```
+
+Run only the browser tests with `auth` in the name:
+```bash
+npx kempo-test -b auth
+```
+
+Run only the node tests with `auth` in the name:
+```bash
+npx kempo-test -n auth
+```
+
+### Individual Test Filtering
+
+You can also filter individual tests within files by providing a second argument. This will find files matching the first filter, then within those files, run only tests whose names (object keys) contain the second filter.
+
+Using the same example files, if your `auth.browser-test.js` contains tests like:
+```javascript
+export default {
+  'should handle user login validation': async ({pass, fail, log}) => { /* ... */ },
+  'should handle user logout process': async ({pass, fail, log}) => { /* ... */ },
+  'should validate password requirements': async ({pass, fail, log}) => { /* ... */ }
+};
+```
+
+Run only tests containing "login" in files containing "auth":
+```bash
+npx kempo-test auth login
+```
+
+Run only browser tests containing "logout" in files containing "auth":
+```bash
+npx kempo-test -b auth logout
+```
+
+Both file and test filtering are case-insensitive and use substring matching.
+
+If you do not provide any filters, all test files will be auto-discovered and run.
+
+### Help
+
+Get usage instructions and see all available options:
+```bash
+npx kempo-test --help
+```

package/gui/components/Collapsible.js

@@ -0,0 +1,54 @@
+import { LitElement, html, css } from '../lit-all.min.js';
+
+window.customElements.define('ktf-collapsible', class extends LitElement {
+	/*
+		Properties
+	*/
+	static properties = {
+		opened: { type: Boolean, reflect: true }
+	}
+	constructor(){
+		super();
+		this.opened = false;
+	}
+	connectedCallback(){
+		super.connectedCallback();
+		if (this.hasAttribute('opened')) this.opened = true;
+	}
+
+	/*
+		Event Handling
+	*/
+	toggle = () => {
+		this.opened = !this.opened;
+	}
+
+	/*
+		Rendering
+	*/
+	render(){
+		return html`
+			<link rel="stylesheet" href="/essential.css">
+			<div class="header">
+				<div class="actions">
+					<slot name="actions"></slot>
+				</div>
+				<button class="no-btn p r title" @click=${this.toggle}>
+					<slot name="title">Show ${this.opened?'Less':'More'}</slot>
+				</button>
+			</div>
+			${this.opened?html`<div class="bt p pb0"><slot></slot></div>`:''}
+		`;
+	}
+	static styles = css`
+		:host {
+			display: block;
+			border: 1px solid var(--c_border, #cccccc);
+			border-radius: var(--radius, 0.25rem);
+			margin-bottom: var(--spacer, 1rem);
+		}
+		.header { display: flex; align-items: center; }
+		.title { flex: 1; text-align: left; }
+		.actions { display: inline-flex; align-items: center; gap: .5rem; }
+	`;
+});

package/gui/components/Icon.js

@@ -0,0 +1,151 @@
+import { LitElement, html, css, unsafeHTML } from '../lit-all.min.js';
+
+// Static cache to store fetched icons across all instances
+const iconCache = new Map();
+
+window.customElements.define('ktf-icon', class extends LitElement {
+	/*
+		Properties
+	*/
+	static properties = {
+		name: { type: String, reflect: true },
+		svg: { type: String },
+		animation: { type: String, reflect: true }
+	}
+	constructor(){
+		super();
+		this.name = '';
+		this.animation = 'none';
+		this.defaultSvg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960""><path fill="currentColor" d="M480-79q-16 0-30.5-6T423-102L102-423q-11-12-17-26.5T79-480q0-16 6-31t17-26l321-321q12-12 26.5-17.5T480-881q16 0 31 5.5t26 17.5l321 321q12 11 17.5 26t5.5 31q0 16-5.5 30.5T858-423L537-102q-11 11-26 17t-31 6Zm0-80 321-321-321-321-321 321 321 321Zm-40-281h80v-240h-80v240Zm40 120q17 0 28.5-11.5T520-360q0-17-11.5-28.5T480-400q-17 0-28.5 11.5T440-360q0 17 11.5 28.5T480-320Zm0-160Z"/></svg>';
+		this.svg = this.defaultSvg;
+	}
+
+	/*
+		Lifecycle Callback
+	*/
+	updated(changedProperties){
+		if(changedProperties.has('name')){
+			this.fetchIcon();
+		}
+	}
+	
+	/*
+		Methods
+	*/
+	async fetchIcon(){
+		if (this.name) {
+			// Check cache first
+			const cached = iconCache.get(this.name);
+			if (cached) {
+				if (cached instanceof Promise) {
+					this.svg = await cached;
+				} else {
+					this.svg = cached;
+				}
+				return;
+			}
+
+			// Cache the promise immediately
+			const promise = (async () => {
+				try {
+					const response = await fetch(`/icons/${this.name}.svg`);
+					return response.ok ? await response.text() : this.defaultSvg;
+				} catch {
+					return this.defaultSvg;
+				}
+			})();
+			
+			iconCache.set(this.name, promise);
+			
+			const svgContent = await promise;
+			iconCache.set(this.name, svgContent);
+			this.svg = svgContent;
+		}
+	}
+
+	/*
+		Rendering
+	*/
+	render(){
+		return html`${unsafeHTML(this.svg)}`;
+	}
+	static styles = css`
+		:host {
+			display: inline-block;
+			height: 1.35em;
+			width: 1.35em;
+			vertical-align: top;
+		}
+
+		/* Animation classes */
+		:host([animation="spin"]) {
+			animation: spin 1s linear infinite;
+		}
+
+		:host([animation="pulse"]) {
+			animation: pulse 1.5s ease-in-out infinite;
+		}
+
+		:host([animation="bounce"]) {
+			animation: bounce 1s ease-in-out infinite;
+		}
+
+		:host([animation="shake"]) {
+			animation: shake 0.5s ease-in-out infinite;
+		}
+
+		:host([animation="fade"]) {
+			animation: fade 2s ease-in-out infinite;
+		}
+
+		:host([animation="flip"]) {
+			animation: flip 2s ease-in-out infinite;
+		}
+
+		/* Keyframe definitions */
+		@keyframes spin {
+			from { transform: rotate(0deg); }
+			to { transform: rotate(360deg); }
+		}
+
+		@keyframes pulse {
+			0%, 100% { 
+				transform: scale(1); 
+				opacity: 1; 
+			}
+			50% { 
+				transform: scale(1.1); 
+				opacity: 0.7; 
+			}
+		}
+
+		@keyframes bounce {
+			0%, 20%, 50%, 80%, 100% {
+				transform: translateY(0);
+			}
+			40% {
+				transform: translateY(-0.3em);
+			}
+			60% {
+				transform: translateY(-0.15em);
+			}
+		}
+
+		@keyframes shake {
+			0%, 100% { transform: translateX(0); }
+			10%, 30%, 50%, 70%, 90% { transform: translateX(-0.1em); }
+			20%, 40%, 60%, 80% { transform: translateX(0.1em); }
+		}
+
+		@keyframes fade {
+			0%, 100% { opacity: 1; }
+			50% { opacity: 0.3; }
+		}
+
+		@keyframes flip {
+			0% { transform: rotateY(0deg); }
+			50% { transform: rotateY(180deg); }
+			100% { transform: rotateY(360deg); }
+		}
+	`
+});