Testing Guidelines

Relevant source files

• CONTRIBUTING.md
• tests/run.js
• tests/suites/draggables.test.js

This document describes the testing infrastructure, test organization, and procedures for ensuring code quality in anime.js. It covers how to run tests, write new test cases, and use the testing utilities provided by the framework. For information about the general development workflow and setup, see Development Setup. For guidelines on submitting code changes, see Pull Request Guidelines.

Purpose and Scope

The anime.js project uses a comprehensive test suite to verify functionality across browser and Node.js environments. This page documents:

• The Mocha-based testing infrastructure
• Commands for running browser and Node.js tests
• Test file organization and naming conventions
• Patterns for writing effective tests
• Available testing utilities and helpers
• Memory leak detection and code quality checks

Testing Infrastructure

The anime.js testing system is built on the Mocha test framework and organized into domain-specific test suites that cover all major subsystems of the library.

Test Framework Architecture

Sources: tests/run.js1-33 tests/suites/draggables.test.js1-10 CONTRIBUTING.md29-31

Test Suite Organization

The test suites are organized by functional domain, with each suite testing a specific subsystem or feature area:

Test Suite	Purpose	Key Areas Tested
engine.test.js	Core animation engine	Timing, update loop, execution
animations.test.js	Animation creation and control	animate(), parameter handling
timelines.test.js	Timeline orchestration	Sequencing, synchronization, labels
draggables.test.js	Draggable interactions	Mouse/touch events, callbacks, physics
svg.test.js	SVG animations	Line drawing, motion paths, attributes
text.test.js	Text manipulation	splitText(), effects, revert
waapi.test.js	Web Animations API	Native browser animations
animatables.test.js	Programmable interfaces	createAnimatable()
tweens.test.js	Tween generation	Value interpolation, decomposition
keyframes.test.js	Keyframe animations	Multi-point animations
timings.test.js	Timing calculations	Duration, delay, offsets
eases.test.js	Easing functions	Springs, beziers, built-in easings
callbacks.test.js	Lifecycle callbacks	onBegin, onUpdate, onComplete
controls.test.js	Playback controls	play(), pause(), seek(), cancel()
stagger.test.js	Stagger effects	Delay patterns, cascading animations
colors.test.js	Color interpolation	Hex, RGB, HSL color spaces
units.test.js	Unit handling	px, %, em, vh, vw conversions
values.test.js	Value parsing	Number extraction, complex values
utils.test.js	Utility functions	DOM helpers, getters, setters
scope.test.js	Scope management	createScope(), context isolation
targets.test.js	Target resolution	Selectors, arrays, NodeLists
parameters.test.js	Parameter handling	Configuration validation
promises.test.js	Promise integration	then(), async/await patterns
directions.test.js	Playback direction	Forward, reverse, alternate
function-based-values.test.js	Dynamic values	Function-based parameters
seconds.test.js	Time units	Second-based timing
build.test.js	Build verification	Module exports, types
scroll.test.js	Scroll animations	Scroll-linked animations
leaks.test.js	Memory leak detection	Resource cleanup verification

Sources: tests/run.js1-30

Running Tests

Browser Tests

Browser tests run in a real browser environment and test DOM manipulation, rendering, and browser-specific APIs:

This command opens a browser window that loads tests/index.html which runs all test suites and displays results in the Mocha reporter interface. The browser environment is necessary for testing:

• DOM element manipulation
• CSS property animations
• SVG attribute modifications
• Browser event handling (mouse, touch, resize)
• Web Animations API (WAAPI) functionality

Sources: CONTRIBUTING.md31

Node.js Tests

Node.js tests verify library functionality in a server-side environment without browser dependencies:

This executes tests/run.js1-33 which imports all test suites and runs them using Mocha with leak detection enabled via mocha.checkLeaks() at tests/run.js31 Node tests are faster than browser tests and suitable for continuous integration pipelines.

Sources: tests/run.js31-32

Development Workflow

When adding new functionality, follow this testing workflow as documented in CONTRIBUTING.md23-32:

1. Run npm run dev-types to build library files while watching for changes
2. Add test cases to the relevant test suite in tests/suites/
3. Run npm run test-browser to verify all tests pass
4. Ensure no memory leaks are detected by Mocha's leak checker

Writing Tests

Test Structure and Patterns

Tests in anime.js follow the Mocha suite() and test() pattern. Here is the structure from tests/suites/draggables.test.js36-50:

Asynchronous Test Pattern

Tests for animations are inherently asynchronous. The standard pattern uses a resolve callback:

Key components:

• Test function accepts resolve parameter
• Setup creates animation/draggable instances
• Callbacks like onSettle, onComplete perform assertions
• resolve() must be called to complete the test

Sources: tests/suites/draggables.test.js37-49

Using Testing Utilities

Import testing utilities from the library and test helpers:

The expect function provides Chai-style assertions:

• expect(value).to.equal(expected)
• expect(value).to.be.above(threshold)
• expect(value).to.be.below(threshold)

Sources: tests/suites/draggables.test.js1-9

Testing with Timers

Use createTimer() to test time-based animations:

This pattern:

• Triggers actions in onBegin
• Continuously updates in onUpdate
• Performs assertions in onComplete
• Uses createTimer() for precise timing control

Sources: tests/suites/draggables.test.js103-116

Simulating User Events

For interactive features like draggables, create synthetic events:

These helpers enable testing of:

• Mouse drag interactions
• Touch gestures
• Event propagation through Shadow DOM

Sources: tests/suites/draggables.test.js11-34

Test Writing Guidelines

Descriptive Test Names

Test descriptions should clearly state what is being tested and expected behavior:

Sources: tests/suites/draggables.test.js37-155

Cleanup and Revert

Always clean up resources after tests to prevent memory leaks and side effects:

Call revert() on animations, draggables, and other instances. Remove dynamically created DOM elements.

Sources: tests/suites/draggables.test.js77-178

Testing Edge Cases

Write tests for edge cases and error conditions:

This test verifies graceful handling when DOM elements are unexpectedly removed.

Sources: tests/suites/draggables.test.js70-79

Testing Callbacks

Verify that callbacks fire the correct number of times:

Track callback invocations with counters and assert expected counts.

Sources: tests/suites/draggables.test.js81-112

Memory Leak Detection

Mocha Leak Checking

The test runner enables leak detection at tests/run.js31:

This feature detects global variable leaks by comparing the global scope before and after tests run. Any unexpected global variables cause test failures.

Sources: tests/run.js31

Leak Test Suite

The dedicated tests/suites/leaks.test.js suite verifies proper cleanup and resource management:

• Animation instance disposal
• Event listener removal
• Timer cancellation
• DOM element cleanup
• Observer disconnection

Sources: tests/run.js29

Preventing Leaks

To avoid memory leaks in tests:

1. Call .revert() on all animation instances
2. Remove event listeners when done
3. Disconnect ResizeObservers and MutationObservers
4. Clean up dynamically created DOM elements
5. Cancel timers and animations

Example from tests/suites/draggables.test.js51-68:

Sources: tests/suites/draggables.test.js51-68

Test Suite Reference

Complete Test Suite List

All test suites are loaded in tests/run.js1-30:

Sources: tests/run.js1-30

Adding New Test Suites

To add a new test suite:

1. Create a new file in tests/suites/ following the naming pattern feature.test.js
2. Import necessary utilities and library modules
3. Structure tests using suite() and test() functions
4. Import the new suite in tests/run.js
5. Run tests to verify they execute correctly

Code Quality Checks

Pre-PR Checklist

Before creating a pull request, verify the following as specified in CONTRIBUTING.md23-32:

1. ✅ Valid JSDoc annotations in all modified .js files
2. ✅ Run npm run dev-types to build anime.esm.js and index.d.ts
3. ✅ Add tests to relevant files in tests/suites/
4. ✅ Run npm run test-browser - all tests pass
5. ✅ No memory leaks detected by mocha.checkLeaks()
6. ✅ TypeScript definitions generated successfully

JSDoc Type Validation

The project uses JSDoc for type definitions. All functions must have proper JSDoc annotations. Global types are defined in src/types.js while local types should be defined in their respective files.

Sources: CONTRIBUTING.md18-21

Test Coverage Requirements

While the project doesn't enforce specific coverage percentages, all new features and bug fixes must include tests. The test should:

• Cover the main use case
• Test edge cases and error conditions
• Verify callback behavior
• Ensure proper cleanup and resource management

Best Practices

Test Organization

Sources: CONTRIBUTING.md23-32

Testing Async Operations

For time-based animations, use these patterns:

1. Callback-based: Use onComplete, onSettle, etc.
2. Timer-based: Use createTimer() for precise timing
3. setTimeout-based: Use native setTimeout() for simple delays

Always call resolve() to complete async tests.

Testing Shadow DOM

When testing features in Shadow DOM contexts, ensure events bubble correctly as demonstrated in tests/suites/draggables.test.js155-194:

Sources: tests/suites/draggables.test.js155-194

Cleanup Pattern

Standard cleanup pattern for all tests:

This ensures resources are freed even if assertions fail.

Integration with Development Workflow

The testing system integrates with the development workflow documented in Development Setup:

1. Development: npm run dev or npm run dev-types watches source files
2. Testing: npm run test:browser or npm run test:node verifies changes
3. Validation: Mocha's leak detection ensures quality
4. Submission: All tests must pass before PR approval

Sources: CONTRIBUTING.md23-32