MDL Test Suite (Version 1.0)

User Manual for MinimumDraw Library Test Suite

Overview

The MinimumDraw Library (MDL) Test Suite is a comprehensive testing tool designed to validate and benchmark the functionality, performance, and reliability of the MDL version 0.92. This manual provides detailed instructions on how to use the test suite effectively.

Note: The MDL Test Suite is designed to work with the MinimumDraw Library version 0.92, which must be available in the same directory as the test suite.

About the MinimumDraw Library

The MinimumDraw Library is a lightweight graphics library originally created by UDI (http://udimac.web.fc2.com) and adapted by Michael Roberts. It provides a range of functions for buffer management, drawing primitives, color handling, pixel manipulation, text rendering, and visual effects.

Test Suite Purpose

The test suite serves several key purposes:

Validate that all MDL functions work correctly
Benchmark performance of various drawing operations
Detect memory leaks and inefficiencies
Provide visual verification of drawing operations
Serve as a demonstration of MDL capabilities

Installation and Setup

System Requirements

LiveCode Development Environment (tested with LiveCode 9.x and above)
Screen resolution: 1024x768 or higher recommended
MDL Library (lib_MDL_0.92.livecode) must be available

Setup Instructions

Ensure you have the MDL Library (lib_MDL_0.92.livecode) file available
Place the MDL Library file in your LiveCode resources folder or in the same directory as the test suite
Open the MDL Test Suite stack
The test suite will automatically try to start using the MDL library during initialization

Note: If the "MDL" button in the top-right corner of the test suite shows green, the library is loaded correctly. If it shows white, you'll need to click it to load the library manually.

User Interface Guide

Main Interface Components

The test suite interface is organized into several key areas:

---------------------------------------------------- | MDL Test Suite | ---------------------------------------------------- | Test Categories | Test Summary | | |-------------------------------| | ☑ Buffer Mgmt | | | ☐ Drawing | | | ☐ Colors | Test Results Display Area | | ☐ Pixels | | | ☐ Text | | | ☐ Effects | | | ☐ Utilities | | | ☐ Memory | | | | | |-----------------| | | [Run Tests] | | | [Clear Log] | | | | | | Options: | | | - Test Speed | | | - Canvas Size | | | - Debug Mode | | | | | ----------------------------------------------------

Interface Areas

Title Area: Displays the test suite title and version
Test Categories: Checkboxes for selecting which test categories to run
Test Canvas: Visual display area for showing drawing operations
Test Summary: Shows overview of test results (total tests, passed, failed, etc.)
Test Results: Detailed log of test outcomes and messages
Debug Output: Technical details and debugging information (only shown when Debug Mode is enabled)
Control Buttons: Run Tests, Clear Log, Export
Test Options: Canvas size, test speed, and debug mode toggles

Test Categories

The test suite includes the following test categories:

1. Buffer Management

Tests core buffer operations, memory tracking, buffer stack operations, and buffer manipulation functions.

Key tests: MdMakeBuffer, MdNewBuffer, MdPushBuffer, MdPopBuffer, MdFillScreen, MdEraseScreen, MdScroll

2. Drawing Primitives

Tests basic shape drawing, filled vs. outline shapes, and validates proper clipping behavior.

Key tests: MdDrawLine, MdDrawRect, MdDrawOval, MdDrawDia, MdDrawStar

3. Color Management

Tests color setting, retrieval, blending operations, and color format handling.

Key tests: MdSetPenColor, MdGetPenColor, MdSetBgColor, MdGetBgColor, MdGetBlendColor

4. Pixel Manipulation

Tests individual pixel operations, pixel arrays, and alpha channel handling.

Key tests: MdSetPixel, MdGetPixel, MdDrawPix, MdDrawPixPat, MdSetPixAlpha

5. Text Rendering

Tests vector text drawing and 7-segment number display.

Key tests: MdDrawText, MdDrawVec, MdDrawNumber, MdDrawSegment

6. Visual Effects

Tests visual transitions and effects.

Key tests: MdGetEffectList, MdUpdate with various effects

7. Utility Functions

Tests rectangle operations, location utilities, and data handling functions.

Key tests: MdPackRect, MdUnpackRect, MdOffsetRect, MdSwap, MdShuffleItems

8. Memory Management

Tests memory usage tracking, buffer pooling efficiency, and checks for memory leaks.

Key tests: Buffer memory usage, multi-buffer operations, memory leak detection

Test Options

Canvas Size

Determines the size of the test canvas:

200 x 200: Smaller canvas, faster testing
400 x 400: Larger canvas, more detailed visualization but slower testing

Test Speed

Controls the thoroughness and speed of testing:

Fast: Runs basic tests quickly with minimal visual feedback (2 second timeout)
Normal: Balanced approach with moderate visual feedback (5 second timeout)
Thorough: Comprehensive testing with detailed visual feedback, including memory leak tests (10 second timeout)

Debug Mode

When enabled, shows detailed technical information in the debug output area, helpful for diagnosing issues.

Running Tests

Basic Test Run

Select the test categories you want to run by clicking the checkboxes
Choose your preferred Canvas Size and Test Speed
Click the "Run Tests" button
Watch the test progress and view results in the Test Results area

Tip: For first-time users, it's recommended to start with just the "Buffer Management" category at "Normal" speed to verify basic functionality.

Recommended Test Strategies

Quick Validation

For a quick check that the MDL library is working correctly:

Select "Buffer Management" and "Drawing Primitives" categories
Set Test Speed to "Fast"
Set Canvas Size to "200 x 200"
Run Tests

Visual Verification

To visually verify drawing operations:

Select a single category (e.g., "Drawing Primitives" or "Text Rendering")
Set Test Speed to "Normal" for longer visual display
Set Canvas Size to "400 x 400" for better visibility
Run Tests and observe the Test Canvas

Comprehensive Testing

For thorough validation, including memory leak detection:

Select all test categories
Set Test Speed to "Thorough"
Be prepared for longer test run time
Enable Debug Mode for detailed diagnostics

Controlling the MDL Library

The "MDL" button in the top-right corner controls the usage of the MDL library:

Green: Library is loaded and in use
White: Library is not loaded

Click the button to toggle between loading and unloading the library.

Understanding Test Results

Test Summary Area

After running tests, the Test Summary area displays:

Total: Total number of tests executed
Passed: Number of tests that passed
Failed: Number of tests that failed
Skipped: Number of tests that were skipped
Pass Rate: Percentage of passed tests
Time: Total execution time in seconds

The background color indicates overall success:

Green: All tests passed
Red: One or more tests failed

Test Results Area

The Test Results area shows detailed information for each test:

✅ Test Name: PASSED - Test completed successfully
❌ Test Name: FAILED - Test failed with details about the failure
⚠️ Test Name: SKIPPED - Test was skipped with reason

For failed tests, additional information is shown:

Expected: What the test expected to happen
Actual: What actually happened

Debug Output Area

When Debug Mode is enabled, this area shows technical details such as:

Execution times for operations
Memory usage statistics
Detailed function parameters and return values
Error messages and stack traces

Exporting Test Results

Export Feature

The test suite allows you to export test results for documentation or further analysis:

Run your desired tests
Click the "Export" button
Choose a filename and location in the save dialog
The complete test log will be saved as a text file

Tip: Exported logs are particularly useful for regression testing - save logs from different versions of the MDL library for comparison.

Advanced Topics

Creating Custom Tests

The test suite is designed to be extensible. If you need to add custom tests:

Create a new handler in the appropriate test module
Use the logTestResult handler to report results
Call your test handler from the relevant category runner

Example of a custom test handler:

on testMyCustomFeature
   local tPassed, tStartTime, tEndTime, tResult, tExpected
   
   try
      -- Setup test conditions
      MdSetPenColor "255,0,0"
      
      -- Measure execution time
      put the milliseconds into tStartTime
      -- Run the MDL function being tested
      put myMDLFunction() into tResult
      put the milliseconds into tEndTime
      
      -- Verify results
      put "expected value" into tExpected
      put (tResult = tExpected) into tPassed
      
      -- Log results
      logTestResult "MyCustomTest", tPassed, \
            "Test description in " & (tEndTime - tStartTime) & "ms", \
            tExpected, tResult
   catch tError
      logTestResult "MyCustomTest", false, tError
   end try
   
   debugLog "Detailed diagnostic information"
end testMyCustomFeature

Performance Benchmarking

The test suite includes performance benchmarking for various MDL operations:

Drawing operations (shapes, lines, pixels)
Buffer manipulations
Text rendering

The fastest operations are typically line drawing and pixel setting, while operations involving alpha blending or complex shapes are slower.

For detailed performance analysis, run with Debug Mode enabled and look for execution times in the Debug Output area.

Memory Analysis

The Memory Management test category is particularly useful for identifying potential memory issues:

The "Buffer Memory Usage" test shows how much memory is consumed by buffers of different sizes
The "Multi-Buffer Operations" test verifies that memory is properly managed during push/pop operations
The "Memory Leaks" test (only in "Thorough" mode) performs extensive operations to detect memory leaks

Watch for unexpectedly high memory differences after operations, which may indicate memory leaks.

Troubleshooting

Common Issues and Solutions

Issue	Possible Causes	Solution
"MDL" button is white, not green	MDL library not loaded	Click the "MDL" button to load the library or ensure lib_MDL_0.92.livecode is in the resources folder
Tests failing in "Buffer Management"	Fundamental MDL issue or incorrect library version	Verify you're using MDL version 0.92, check library path
Visual tests show no output	Test canvas not visible or improperly initialized	Reset test canvas, try increasing canvas size, or restart test suite
Tests running very slowly	Thorough mode or large canvas size	Switch to "Fast" mode or reduce canvas size to "200 x 200"
Memory leak warnings	Genuine leaks or temporary memory allocation	Run memory tests again to confirm, check Debug Output for details
Test suite crashes	Out of memory or stack overflow	Increase LiveCode memory limits, run fewer tests at once

Getting Additional Help

If you encounter issues not covered in this manual:

Enable Debug Mode to get more detailed error information
Check the MDL library documentation for function specifications
Export the test results and share them when seeking help
Refer to the original MDL implementation at http://udimac.web.fc2.com for context

Conclusion

The MDL Test Suite provides a comprehensive framework for validating and benchmarking the MinimumDraw Library. By regularly running these tests, you can ensure that the library is functioning correctly and efficiently in your environment.

Note: This user manual is for version 1.0 of the MDL Test Suite, designed for MDL library version 0.92. Future versions of either component may require updated testing procedures.