Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/DEVELOPER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -705,12 +705,14 @@ const handleInput = (event: Event) => {

### Unit Testing

Use Vitest for unit tests:
All unit tests live directly in the top-level `tests/` directory following the naming convention `tests/<algorithm-name>-algorithm.test.ts` (e.g. `tests/knn-algorithm.test.ts`, `tests/linear-regression-algorithm.test.ts`).

Tests use Vitest and should cover `fit()`, `predict()`, performance metrics (`getMetrics()`), visualization payloads (`getVisualizationData()`), input validation, and `reset()`.

```typescript
// algorithms/__tests__/ExampleAlgorithm.test.ts
// tests/example-algorithm.test.ts
import { describe, it, expect } from 'vitest';
import { ExampleAlgorithm } from '../ExampleAlgorithm';
import { ExampleAlgorithm } from '../algorithms/regression/ExampleAlgorithm';

describe('ExampleAlgorithm', () => {
it('should initialize with default parameters', () => {
Expand Down
140 changes: 140 additions & 0 deletions tests/feature-scaling-algorithm.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
/**
* Feature Scaling Algorithm Tests
*
* Tests for normalization (Min-Max) and standardization (Z-Score) preprocessing algorithms
*/

import { describe, it, expect, beforeEach } from 'vitest';
import { FeatureScaling } from '../algorithms/preprocessing/FeatureScaling';

describe('FeatureScaling Algorithm', () => {
let scaler: FeatureScaling;

beforeEach(() => {
scaler = new FeatureScaling();
});

describe('Min-Max Normalization', () => {
it('should scale features to [0, 1] range', () => {
const data = [
[0, 10],
[5, 20],
[10, 30]
];
scaler.setData(data);

const result = scaler.normalize();

expect(result.method).toBe('normalize');
expect(result.scaled).toEqual([
[0, 0],
[0.5, 0.5],
[1, 1]
]);

expect(result.statistics.originalMin).toEqual([0, 10]);
expect(result.statistics.originalMax).toEqual([10, 30]);
expect(result.statistics.scaledMin).toEqual([0, 0]);
expect(result.statistics.scaledMax).toEqual([1, 1]);
});

it('should handle constant feature columns without division by zero', () => {
const data = [
[5, 10],
[5, 20],
[5, 30]
];
scaler.setData(data);

const result = scaler.normalize();

// Constant column should be scaled to 0
expect(result.scaled.map(row => row[0])).toEqual([0, 0, 0]);
expect(result.scaled.map(row => row[1])).toEqual([0, 0.5, 1]);
});
});

describe('Z-Score Standardization', () => {
it('should transform features to have zero mean and unit variance', () => {
// Symmetrical data around mean
const data = [
[-2, 10],
[0, 20],
[2, 30]
];
scaler.setData(data);

const result = scaler.standardize();

expect(result.method).toBe('standardize');
expect(result.scaled).toHaveLength(3);

// Mean should be 0 for both features
const mean0 = (result.scaled[0][0] + result.scaled[1][0] + result.scaled[2][0]) / 3;
const mean1 = (result.scaled[0][1] + result.scaled[1][1] + result.scaled[2][1]) / 3;

expect(mean0).toBeCloseTo(0, 5);
expect(mean1).toBeCloseTo(0, 5);

// Statistics check
expect(result.statistics.originalMean![0]).toBeCloseTo(0, 5);
expect(result.statistics.originalMean![1]).toBeCloseTo(20, 5);
expect(result.statistics.scaledMean![0]).toBeCloseTo(0, 5);
expect(result.statistics.scaledMean![1]).toBeCloseTo(0, 5);
expect(result.statistics.scaledStd![0]).toBeCloseTo(1, 5);
expect(result.statistics.scaledStd![1]).toBeCloseTo(1, 5);
});

it('should handle zero-variance constant column', () => {
const data = [
[7, 100],
[7, 200],
[7, 300]
];
scaler.setData(data);

const result = scaler.standardize();

// Constant feature standardizes to 0 (since std is 0)
expect(result.scaled.map(row => row[0])).toEqual([0, 0, 0]);
expect(result.statistics.originalStd![0]).toBe(0);
});
});

describe('State Management and Reset', () => {
it('should initialize with constructor data', () => {
const initial = [[1, 2], [3, 4]];
const s = new FeatureScaling(initial);
const res = s.getResult();

expect(res.original).toEqual(initial);
expect(res.scaled).toEqual(initial);
expect(res.method).toBe('none');
});

it('should reset scaled data and statistics back to none', () => {
const data = [[1, 2], [3, 4]];
scaler.setData(data);
scaler.normalize();

expect(scaler.getResult().method).toBe('normalize');

scaler.reset();
const afterReset = scaler.getResult();

expect(afterReset.method).toBe('none');
expect(afterReset.scaled).toEqual(data);
expect(afterReset.statistics).toEqual({});
});
});

describe('Error Handling', () => {
it('should throw error when normalizing empty data', () => {
expect(() => scaler.normalize()).toThrow('No data to normalize');
});

it('should throw error when standardizing empty data', () => {
expect(() => scaler.standardize()).toThrow('No data to standardize');
});
});
});
213 changes: 213 additions & 0 deletions tests/kmeans-algorithm.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,213 @@
/**
* K-Means Algorithm Tests
*
* Tests for K-Means Clustering algorithm with k-means++ and random initialization
* Requirements: 2.4, 4.6
*/

import { describe, it, expect, beforeEach } from 'vitest';
import { KMeans } from '../algorithms/clustering/KMeans';

describe('KMeans Algorithm', () => {
let kmeans: KMeans;

beforeEach(() => {
kmeans = new KMeans({
k: 2,
maxIterations: 50,
tolerance: 1e-4,
initialization: 'kmeans++',
randomSeed: 42
});
});

describe('Basic Clustering Functionality', () => {
it('should separate two well-spaced 2D clusters', async () => {
// Two distinct clusters around (1, 1) and (10, 10)
const X = [
[0.9, 1.1],
[1.0, 0.9],
[1.1, 1.0],
[0.8, 1.2],
[9.9, 10.1],
[10.0, 9.9],
[10.1, 10.0],
[9.8, 10.2]
];

await kmeans.fit(X);
const assignments = kmeans.predict(X);

expect(assignments).toHaveLength(8);

// First 4 samples should belong to one cluster, next 4 to the other
const clusterA = assignments[0];
const clusterB = assignments[4];

expect(clusterA).not.toBe(clusterB);
expect(assignments.slice(0, 4).every(c => c === clusterA)).toBe(true);
expect(assignments.slice(4, 8).every(c => c === clusterB)).toBe(true);
});

it('should assign unseen test points to nearest centroid', async () => {
const X = [
[1, 1],
[1.2, 0.8],
[10, 10],
[10.2, 9.8]
];

await kmeans.fit(X);

const testPoints = [
[1.1, 1.1], // Close to (1, 1)
[9.9, 10.1] // Close to (10, 10)
];
const predictions = kmeans.predict(testPoints);

const trainPredictions = kmeans.predict([[1, 1], [10, 10]]);
expect(predictions[0]).toBe(trainPredictions[0]);
expect(predictions[1]).toBe(trainPredictions[1]);
});
});

describe('Initialization Modes', () => {
it('should support random initialization', async () => {
const kmeansRandom = new KMeans({
k: 2,
maxIterations: 50,
tolerance: 1e-4,
initialization: 'random',
randomSeed: 123
});

const X = [
[0, 0],
[0.2, 0.1],
[5, 5],
[5.1, 4.9]
];

await kmeansRandom.fit(X);
const centroids = kmeansRandom.getCentroids();

expect(centroids).toHaveLength(2);
expect(centroids[0]).toHaveLength(2);
expect(centroids[1]).toHaveLength(2);
});

it('should record iterative cluster history', async () => {
const X = [
[1, 1],
[2, 2],
[8, 8],
[9, 9]
];

await kmeans.fit(X);
const history = kmeans.getClusterHistory();

expect(Array.isArray(history)).toBe(true);
expect(history.length).toBeGreaterThan(0);
expect(history[0]).toHaveProperty('centroids');
expect(history[0]).toHaveProperty('assignments');
expect(history[0]).toHaveProperty('inertia');
});
});

describe('Metrics', () => {
it('should return empty metrics object before fitting', () => {
expect(kmeans.getMetrics()).toEqual({});
});

it('should calculate clustering metrics (inertia, silhouetteScore, clusterSizes)', async () => {
const X = [
[1, 1],
[1.2, 0.8],
[8, 8],
[8.2, 7.8]
];

await kmeans.fit(X);
const metrics = kmeans.getMetrics();

expect(metrics.inertia).toBeDefined();
expect(metrics.inertia!).toBeGreaterThanOrEqual(0);
expect(metrics.silhouetteScore).toBeDefined();
expect(metrics.silhouetteScore!).toBeGreaterThan(0);
expect(metrics.iterations).toBeDefined();
expect(metrics.clusterSizes).toBeDefined();
expect(metrics.clusterSizes).toHaveLength(2);
expect(metrics.clusterSizes![0] + metrics.clusterSizes![1]).toBe(4);
});
});

describe('Visualization Data', () => {
it('should return empty array before training', () => {
expect(kmeans.getVisualizationData()).toEqual([]);
});

it('should provide 2D scatter and line visualization data for 2D clusters', async () => {
const X = [
[1, 1],
[2, 2],
[8, 8],
[9, 9]
];

await kmeans.fit(X);
const viz = kmeans.getVisualizationData();

expect(Array.isArray(viz)).toBe(true);
expect(viz.length).toBe(2);

const scatter = viz.find(v => v.type === 'scatter2d');
const line = viz.find(v => v.type === 'line');

expect(scatter).toBeDefined();
expect(scatter!.data).toHaveProperty('centroids');
expect(scatter!.data).toHaveProperty('cluster0');
expect(scatter!.data).toHaveProperty('cluster1');

expect(line).toBeDefined();
expect(line!.data.name).toBe('Inertia');
});
});

describe('Error Handling', () => {
it('should throw error when predicting before training', () => {
expect(() => kmeans.predict([[1, 1]])).toThrow('K-Means Clustering must be trained before making predictions');
});

it('should throw error when k is greater than number of samples', async () => {
const kLarge = new KMeans({ k: 5, maxIterations: 10, tolerance: 1e-4, initialization: 'kmeans++' });
await expect(kLarge.fit([[1, 1], [2, 2]])).rejects.toThrow('cannot exceed number of samples');
});

it('should throw error when k is less than 1', async () => {
const kZero = new KMeans({ k: 0, maxIterations: 10, tolerance: 1e-4, initialization: 'kmeans++' });
await expect(kZero.fit([[1, 1]])).rejects.toThrow('Number of clusters must be at least 1');
});

it('should throw error on predict with mismatched feature dimensions', async () => {
const X = [[1, 2], [3, 4], [5, 6]];
await kmeans.fit(X);
expect(() => kmeans.predict([[1, 2, 3]])).toThrow();
});
});

describe('Reset', () => {
it('should reset model state and centroids', async () => {
const X = [[1, 1], [2, 2], [5, 5], [6, 6]];
await kmeans.fit(X);
expect(() => kmeans.predict([[1, 1]])).not.toThrow();

kmeans.reset();
expect(() => kmeans.predict([[1, 1]])).toThrow();
expect(kmeans.getCentroids()).toHaveLength(0);
expect(kmeans.getAssignments()).toHaveLength(0);
expect(kmeans.getMetrics()).toEqual({});
expect(kmeans.getVisualizationData()).toEqual([]);
});
});
});
Loading
Loading