smalltalkCI

Community-supported framework for testing Smalltalk projects on Linux, OS X, and Windows with built-in support for Travis CI and AppVeyor.

It is inspired by builderCI and aims to provide a uniform and easy way to load and test Smalltalk projects.

Features

Simple configuration via .smalltalk.ston, .travis.yml, and appveyor.yml (see below for templates)
Compatible across different Smalltalk dialects (Squeak, Pharo, GemStone)
Runs on Travis CI's container-based infrastructure ("Builds start in seconds")
Supports Linux, macOS, and Windows and can be run locally (e.g. for debug purposes)
Exports test results in the JUnit XML format as part of the Travis build log
Supports coverage testing and publishes results to coveralls.io

## How To Enable Travis CI For Your Smalltalk Project

Export your project in a compatible format (e.g. FileTree).
Enable Travis CI for your repository.
Create a .travis.yml and specifiy the Smalltalk image(s) you want your project to be tested against.
Create a .smalltalk.ston (see below for templates) and specify how to load and test your project.
Push all of this to GitHub and enjoy your fast Smalltalk builds!

## How To Test Your Smalltalk Project Locally

You can use smalltalkCI to run your project's tests locally. Just clone or download smalltalkCI and then you are able to initiate a local build in headful mode like this:

/path/to/smalltalkCI/run.sh --headful /path/to/your/projects/.smalltalk.ston

IMAGE can be one of the supported images. You may also want to have a look at all supported options.

Please note: All builds will be stored in _builds within smalltalkCI's directory. You may want to delete single or all builds if you don't need them as they can take up a lot of space on your drive.

## List Of Supported Images

Squeak	Pharo	GemStone	Moose
`Squeak-trunk`	`Pharo-alpha`	`GemStone-3.3.x`	`Moose-trunk`
`Squeak-5.1`	`Pharo-stable`	`GemStone-3.2.x`	`Moose-6.1`
`Squeak-5.0`	`Pharo-6.0`	`GemStone-3.1.0.x`	`Moose-6.0`
`Squeak-4.6`	`Pharo-5.0`	`Gemstone-2.4.x`
`Squeak-4.5`	`Pharo-4.0`
	`Pharo-3.0`

## Templates

Minimal `.smalltalk.ston` Template

The following SmalltalkCISpec will load BaselineOfMyProject using Metacello/FileTree from the ./packages directory in Squeak, Pharo, and GemStone. See below how you can [customize your SmalltalkCISpec.] (#SmalltalkCISpec)

SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      #baseline : 'MyProject',
      #directory : 'packages',
      #platforms : [ #squeak, #pharo, #gemstone ]
    }
  ]
}

`.travis.yml` Template

language: smalltalk
sudo: false

# Select operating system(s)
os:
  - linux
  - osx

# Select compatible Smalltalk image(s)
smalltalk:
  - Squeak-trunk
  - Squeak-5.1
  - Squeak-5.0
  - Squeak-4.6
  - Squeak-4.5

  - Pharo-alpha
  - Pharo-stable
  - Pharo-6.0
  - Pharo-5.0
  - Pharo-4.0
  - Pharo-3.0

  - GemStone-3.3.0
  - GemStone-3.2.12
  - GemStone-3.1.0.6

# Uncomment to enable caching (only useful for GemStone builds (3x faster))
#cache:
#  directories:
#    - $SMALLTALK_CI_CACHE

`appveyor.yml` Template

environment:
  CYG_ROOT: C:\cygwin
  CYG_BASH: C:\cygwin\bin\bash
  CYG_CACHE: C:\cygwin\var\cache\setup
  CYG_EXE: C:\cygwin\setup-x86.exe
  CYG_MIRROR: http://cygwin.mirror.constant.com
  SCI_RUN: /cygdrive/c/smalltalkCI-master/run.sh
  matrix:
    # Currently, only Squeak and Pharo images are supported on AppVeyor.
    - SMALLTALK: Squeak-trunk
    - SMALLTALK: Squeak-5.0
    - SMALLTALK: Pharo-6.0
    - SMALLTALK: Pharo-5.0
    # ...

platform:
  - x86

install:
  - '%CYG_EXE% -qnNdO -R "%CYG_ROOT%" -s "%CYG_MIRROR%" -l "%CYG_CACHE%" -P unzip'
  - ps: Start-FileDownload "https://github.com/hpi-swa/smalltalkCI/archive/master.zip" "C:\smalltalkCI.zip"
  - 7z x C:\smalltalkCI.zip -oC:\ -y > NULL

build: false

test_script:
  - '%CYG_BASH% -lc "cd $APPVEYOR_BUILD_FOLDER; exec 0</dev/null; $SCI_RUN"'

Advanced Templates

`.travis.yml` template with multiple smalltalkCI configurations

The build matrix can be expanded with multiple smalltalkCI configuration files using the smalltalk_config key:

language: smalltalk
sudo: false

smalltalk:
  - Squeak-trunk
  - Pharo-alpha

smalltalk_config:
  - .smalltalk.ston
  - .bleedingEdge.ston

The .bleedingEdge.ston configuration may look like this:

SmalltalkCISpec {
  #loading : [
    SCIMetacelloLoadSpec {
      ...
      #load : [ 'CoreWithExtras' ],
      #version : #bleedingEdge
    }
  ],
  ...
}

Resulting build matrix

Smalltalk	Config	OS
`Squeak-trunk`	`.smalltalk.ston`	Linux
`Squeak-trunk`	`.bleedingEdge.ston`	Linux
`Pharo-alpha`	`.smalltalk.ston`	Linux
`Pharo-alpha`	`.bleedingEdge.ston`	Linux

`.travis.yml` template with additional jobs

It is possible to add additional jobs to the build matrix using the smalltalk_config key:

language: smalltalk
sudo: false

os: osx

smalltalk:
  - Squeak-5.1
  - Pharo-6.0

matrix:
  include:
    - smalltalk: Squeak-trunk
      smalltalk_config: .bleedingEdge.ston
    - smalltalk: Pharo-alpha
      smalltalk_config: .bleedingEdge.ston
  allow_failures: # Allow bleeding edge builds to fail
    - smalltalk_config: .bleedingEdge.ston

Resulting build matrix

Smalltalk	Config	OS
`Squeak-5.1`	`.smalltalk.ston`	macOS
`Pharo-6.0`	`.smalltalk.ston`	macOS
`Squeak-trunk`	`.bleedingEdge.ston`	macOS
`Pharo-alpha`	`.bleedingEdge.ston`	macOS

`appveyor.yml` template with additional jobs

It is possible to add additional jobs to the build matrix using environment.matrix as follows:

environment:
  CYG_ROOT: C:\cygwin
  CYG_BASH: C:\cygwin\bin\bash
  CYG_CACHE: C:\cygwin\var\cache\setup
  CYG_EXE: C:\cygwin\setup-x86.exe
  CYG_MIRROR: http://cygwin.mirror.constant.com
  SCI_RUN: /cygdrive/c/SMALLTALKCI-master/run.sh

  matrix:
    - SMALLTALK: Squeak-5.1
    - SMALLTALK: Squeak-trunk
      SMALLTALK_CONFIG: .bleedingEdge.ston
    - SMALLTALK: Pharo-6.0
    - SMALLTALK: Pharo-alpha
      SMALLTALK_CONFIG: .bleedingEdge.ston

platform:
  - x86

install:
  - '%CYG_EXE% -qnNdO -R "%CYG_ROOT%" -s "%CYG_MIRROR%" -l "%CYG_CACHE%" -P unzip'
  - ps: Start-FileDownload "https://github.com/hpi-swa/SMALLTALKCI/archive/master.zip" "C:\SMALLTALKCI.zip"
  - 7z x C:\SMALLTALKCI.zip -oC:\ -y > NULL

build: false

test_script:
  - '%CYG_BASH% -lc "cd $APPVEYOR_BUILD_FOLDER; exec 0</dev/null; $SCI_RUN $SMALLTALK_CONFIG"'

Resulting build matrix

Smalltalk	Config
`Squeak-5.1`	`.smalltalk.ston`
`Squeak-trunk`	`.bleedingEdge.ston`
`Pharo-6.0`	`.smalltalk.ston`
`Pharo-alpha`	`.bleedingEdge.ston`

Further Configuration

### Setting Up A Custom `.smalltalk.ston`

smalltalkCI requires a .smalltalk.ston configuration file which can be customized for a project to cover various use cases. The .smalltalk.ston must be a valid STON file and has to contain a single SmalltalkCISpec object. This object can hold one or more load specifications in #loading and configurations for the TestCase selection in #testing.

SmalltalkCISpec {
  #loading : [
    // List Of Load Specifications...
  ],
  #testing : {
    // TestCase Selection...
  }
}

#### Project Loading Specifications smalltalkCI supports different formats for loading Smalltalk projects and for each, there is a loading specification. One or more of those loading specifications have to be provided in the `#loading` list as part of a [`SmalltalkCISpec`](#SmalltalkCISpec). smalltalkCI will load all specifications that are compatible with the selected Smalltalk image (specified via `#platforms`).

SCIMetacelloLoadSpec

A SCIMetacelloLoadSpec loads a project either via the specified Metacello #baseline or the Metacello #configuration. If a #directory is specified, the project will be loaded using FileTree/Metacello from the given directory. Otherwise, it will be loaded from the specified #repository.

SCIMetacelloLoadSpec {
  #baseline : 'MyProject',                            // Define MC Baseline
  #configuration : 'MyProject',                       // Alternatively, define MC Configuration
  #directory : 'packages',                            // Path to packages if FileTree is used
  #repository : 'http://smalltalkhub.com/mc/...',     // Alternatively, define MC repository
  #onWarningLog : true,                               // Log Warning messages to Transcript
  #failOn : [ #OCUndeclaredVariableWarning ],         // Fail build on provided list of Warnings
  #useLatestMetacello : true,                         // Upgrade Metacello before loading
  #load : [ 'default' ],                              // Define MC load attributes
  #platforms : [ #squeak, #pharo, #gemstone ],        // Define compatible platforms
  #version : '1.0.0'                                  // Define MC version (for MC
                                                      // Configurations only)
}

SCIMonticelloLoadSpec

A SCIMonticelloLoadSpec loads a project with Monticello. It is possible to load the latest version of packages from a remote repository (#packages) or specific versions (#versions).

SCIMonticelloLoadSpec {
  #url : 'http://ss3.gemtalksystems.com/ss/...',      // Define URL for repository
  #packages : ['MyProject-Core', 'MyProject-Tests'],  // Load packages and/or
  #versions : ['MyProject-Core-aa.12'],               // Load specific versions
  #platforms : [ #squeak, #pharo, #gemstone ]         // Define compatible platforms
}

SCIGoferLoadSpec

A SCIGoferLoadSpec works similar to a SCIMonticelloLoadSpec, but uses Gofer on top of Monticello to load a project.

SCIGoferLoadSpec {
  #url : 'http://smalltalkhub.com/mc/...',            // Define URL for repository
  #packages : ['MyProject-Core', 'MyProject-Tests'],  // Load packages and/or
  #versions : ['MyProject-Core-aa.12'],               // Load specific versions
  #platforms : [ #squeak, #pharo, #gemstone ]         // Define compatible platforms
}

TestCase Selection

smalltalkCI runs a list of TestCases during a build. By default, smalltalkCI will use a list of all TestCases that it has loaded into the image. It is possible to adjust this list using the #testing slot. In general, TestCases can be selected on class-level (#classes), on category-level (#categories), on package-level (#packages) and on project-level (#projects, GemStone only). #classes expects a list of class name symbols, #categories and #packages expect category names and prefixes or package names and prefixes respectively. The default list can be replaced by a list of all TestCases that are present in the image by setting #allTestCases to true. Additionally, it is possible to add (#include) or remove (#exclude) classes from this list. The list can also be specified explicitly which means that only these TestCases will run.

SmalltalkCISpec {
  ...
  #testing : {
    // Include specific TestCases
    #include : {
      #classes : [ #AnotherProjectTestCase ],
      #categories : [ 'AnotherProject-Tests' ],
      #packages : [ 'AnotherProject.*' ],
      #projects : [ 'BaselineOfMyProject' ]
    },

    // Exclude specific TestCases from testing
    #exclude : {
      #classes : [ #AnotherProjectTestCase ],
      #categories : [ 'AnotherProject-Tests' ],
      #packages : [ 'AnotherProject.*' ],
      #projects : [ 'ConfigurationOfMyOtherProject' ]
    },

    #allTestCases : true, // Run all TestCases in image

    // Define TestCases explicitly
    #classes : [ #MyProjectTestCase ],
    #categories : [ 'MyProject-*' ],
    #packages : [ 'MyProject.*' ],
    #projects : [ 'BaselineOfMyProject' ],

    // Other options
    #defaultTimeout : 30, // In seconds (Squeak-only)
    #hidePassingTests : true // Hide passing tests when printing to stdout
  }
}

Command Line Options

smalltalkCI has a couple of command line options that can be useful for debugging purposes or when used locally:

USAGE: run.sh [options] /path/to/project/your_smalltalk.ston

This program prepares Smalltalk images/vms, loads projects and runs tests.

OPTIONS:
  --clean             Clear cache and delete builds.
  -d | --debug        Enable debug mode.
  -h | --help         Show this help text.
  --headful           Open vm in headful mode and do not close image.
  --install           Install symlink to this smalltalkCI instance.
  --no-tracking       Disable collection of anonymous build metrics (Travis CI & AppVeyor only).
  -s | --smalltalk    Overwrite Smalltalk image selection.
  --uninstall         Remove symlink to any smalltalkCI instance.
  -v | --verbose      Enable 'set -x'.

EXAMPLE:
  run.sh -s "Squeak-trunk" --headful /path/to/project/.smalltalk.ston

Collection Of Anonymous Build Metrics

smalltalkCI collects anonymous build metrics (Smalltalk dialect, CI environment, build status, build duration) for public repositories when running on Travis CI or AppVeyor. This allows to identify build errors caused by smalltalkCI updates and therefore helps to improve the service. It is possible to opt-out by using the --no-tracking option.

Travis-specific Options

Jobs on Travis CI timeout if they don't produce output for more than 10 minutes. In case of long running tests, it is possible to increase this timeout by setting $SMALLTALK_CI_TIMEOUT in your .travis.yml to a value greater than 10:

env:
- SMALLTALK_CI_TIMEOUT=30

The above sets the timeout to 30 minutes. Please note that Travis CI enforces a total build timeout of 50 minutes.

Using A Different smalltalkCI Branch Or Fork

By default, the smalltalkCI master branch is used to perform a build. It is possible to select a different smalltalkCI branch or fork for testing/debugging purposes by adding the following to the .travis.yml:

smalltalk_edge:
  source: hpi-swa/smalltalkCI
  branch: dev

Contributing

Please feel free to open issues or to send pull requests if you'd like to discuss an idea or a problem.

Projects Using smalltalkCI

In alphabetical order:

@Cormas: Cormas.
@dalehenrich: obex, tode.
@DuneSt: Heimdall, MaterialDesignLite, PrismCodeDisplayer.
@dynacase: borm-editor, borm-model, borm-persistence, class-editor, demo-editor, dynacase, dynacase-model, fsm-editor.
@HPI-BP2015H: squeak-parable.
@HPI-SWA-Teaching: Algernon-Launcher.
@hpi-swa: animations, Ohm-S, vivide.
@marianopeck: OSSubprocess, FFICHeaderExtractor.
@pharo-project: pharo-project-proposals.
@PolyMathOrg: PolyMath.
@SeasideSt: Grease, Parasol, Seaside.
@SergeStinckwich: PlayerST.
@theseion: Fuel.
@Uko: GitHubcello, QualityAssistant, Renraku.
@UMMISCO: Kendrick.
@zecke: osmo-smsc.
More Projects...

Feel free to send a PR to add your Smalltalk project to the list. Please add [ci skip] to your commit message.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

smalltalkCI

Table Of Contents

Features

Minimal `.smalltalk.ston` Template

`.travis.yml` Template

`appveyor.yml` Template

Advanced Templates

Resulting build matrix

Resulting build matrix

Resulting build matrix

Further Configuration

SCIMetacelloLoadSpec

SCIMonticelloLoadSpec

SCIGoferLoadSpec

TestCase Selection

Command Line Options

Collection Of Anonymous Build Metrics

Travis-specific Options

Using A Different smalltalkCI Branch Or Fork

Contributing

Projects Using smalltalkCI

Files

README.md

Latest commit

History

README.md

File metadata and controls

smalltalkCI

Table Of Contents

Features

Minimal .smalltalk.ston Template

.travis.yml Template

appveyor.yml Template

Advanced Templates

Resulting build matrix

Resulting build matrix

Resulting build matrix

Further Configuration

SCIMetacelloLoadSpec

SCIMonticelloLoadSpec

SCIGoferLoadSpec

TestCase Selection

Command Line Options

Collection Of Anonymous Build Metrics

Travis-specific Options

Using A Different smalltalkCI Branch Or Fork

Contributing

Projects Using smalltalkCI

Minimal `.smalltalk.ston` Template

`.travis.yml` Template

`appveyor.yml` Template