How to Use the Command 'smalltalkci' (with Examples)

SmalltalkCI is a dynamic and efficient framework employed for running tests in Smalltalk projects across various continuous integration services like GitHub Actions, Travis CI, AppVeyor, GitLab CI, among others. It simplifies testing workflows by allowing automatic execution of tests, download of images, and cleanup operations, thus providing a streamlined process for developers working in the Smalltalk programming environment. Below, we delve into several use cases that illustrate how SmalltalkCI can be utilized for various functionalities.

Use Case 1: Run Tests for a Configuration File

Code:

smalltalkci path/to/.smalltalk.ston

Motivation:

This use case is beneficial when you have multiple configuration files for different environments or projects. By specifying a particular configuration file, you ensure that the SmalltalkCI framework runs tests tailored to this specific setup. This is especially useful when working in a diverse development team or environment where different configurations might exist.

Explanation:

• smalltalkci: This is the command for invoking the SmalltalkCI tool.
• path/to/.smalltalk.ston: This argument is the file path to the specific .smalltalk.ston configuration file. The .ston files are typically written in a lightweight data exchange format which is quite similar to JSON but adapted for Smalltalk environments.

Example Output:

Running tests for project configuration at path/to/.smalltalk.ston
All tests passed successfully.

Use Case 2: Run Tests for the .smalltalk.ston Configuration in the Current Directory

Code:

smalltalkci

Motivation:

Sometimes it is convenient to run tests using the default configuration without having to specify a path each time, particularly when working in a single project directory. This approach is optimal when the .smalltalk.ston file is located in the working directory and you want to quickly test using the preset configuration.

Explanation:

• smalltalkci: When run without any arguments, it defaults to locating and utilizing the .smalltalk.ston configuration file in the current working directory.

Example Output:

Using default configuration in the current directory.
Starting test suite...
Test suite completed. No errors found.

Use Case 3: Debug Tests in Headful Mode (Show VM Window)

Code:

smalltalkci --headful

Motivation:

Running tests in headful mode is essential for developers who need to visually debug the tests by observing the behavior inside the virtual machine (VM). This can be crucial when diagnosing UI-related issues or when the headless mode test results don’t provide sufficient information to debug effectively.

Explanation:

• smalltalkci: Executes the SmalltalkCI framework.
• --headful: This flag triggers the VM to run in a mode where the GUI is displayed, allowing developers to interact with the tests as they execute.

Example Output:

Launching tests in headful mode.
Virtual machine window opened.
Execution in progress...
Tests concluded. All functionalities are operational.

Use Case 4: Download and Prepare a Well-Known Smalltalk Image for the Tests

Code:

smalltalkci --smalltalk Squeak64-Trunk

Motivation:

Balancing multiple Smalltalk project requirements often involves testing across different versions or branches of Smalltalk images. By specifying Squeak64-Trunk, developers can easily download and set up the current development branch of the Squeak Smalltalk for testing, allowing them to test on the latest version and features.

Explanation:

• smalltalkci: Command to start the SmalltalkCI tool.
• --smalltalk: This option indicates that the following argument will be the identifier of the Smalltalk image to be used.
• Squeak64-Trunk: The specific image name or identifier which represents the development version of Squeak that should be downloaded and prepared for testing.

Example Output:

Downloading Squeak64-Trunk image...
Preparing Squeak development environment...
Image setup complete. Proceeding with tests.

Use Case 5: Specify a Custom Smalltalk Image and VM

Code:

smalltalkci --image path/to/Smalltalk.image --vm path/to/vm

Motivation:

When you have a customized Smalltalk environment or a specialized VM that must be specifically tested, this use case allows you to define both the image and VM explicitly. This flexibility ensures that tests reflect the actual deployment environment as closely as possible.

Explanation:

• smalltalkci: Executes the SmalltalkCI framework.
• --image: This argument specifies the file path to a custom Smalltalk image file that the tests should run against.
• path/to/Smalltalk.image: The path where the custom Smalltalk image is located.
• --vm: This option denotes the file path to the VM executable used to run the tests.
• path/to/vm: The path indicating where the custom VM executable resides.

Example Output:

Using Custom Smalltalk Image: path/to/Smalltalk.image
Custom VM: path/to/vm is starting...
Tests are being executed.
Custom setup testing completed successfully.

Use Case 6: Clean Up Caches and Delete Builds

Code:

smalltalkci --clean

Motivation:

Development often entails performing numerous test builds which can lead to clutter and consume substantial storage space over time. The --clean command is designed to perform regular maintenance by clearing caches and deleting outdated build artifacts, promoting better resource management and ensuring a clean working environment.

Explanation:

• smalltalkci: The command to run the SmalltalkCI tool.
• --clean: This flag initiates a cleanup process where caches are cleared, and residual build files are removed.

Example Output:

Cleaning process initiated...
All caches cleared.
Builds deleted.
Cleanup was successful; system resources optimized.

Conclusion

Utilizing the SmalltalkCI command allows developers to enhance their testing processes by automating and customizing test runs for Smalltalk projects efficiently. With versatile use cases like defining specific configurations, running headful modes for debugging, downloading ready-to-use Smalltalk images, and performing system cleanup, SmalltalkCI proves to be a comprehensive tool tailored for Smalltalk testing environments.