smalltalkCI

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 {
  #name : 'My Name', // Name of the SmalltalkCISpec (optional)
  #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. 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 : 'src',                                 // Path to source-code directory were are packages (i.e. 'packages' or 'src'), in case of packages are not on root
  #failOn : [ #OCUndeclaredVariableWarning ],         // Fail build on provided list of Warnings
  #ignoreImage : true,                                // If true, Metacello will force a load of a package, overriding a previously existing one
  #load : [ 'default' ],                              // Define MC load attributes
  #onConflict : #useIncoming,                         // When there is a conflict between loaded sources and incoming sources (can be #useIncoming|#useLoaded)
  #onUpgrade : #useIncoming,                          // When loaded sources are an older version than incoming sources (can be #useIncoming|#useLoaded)
  #onWarningLog : true,                               // Log Warning messages to Transcript
  #platforms : [ #squeak, #pharo, #gemstone ],        // Define compatible platforms
  #repository : 'http://smalltalkhub.com/mc/...',     // Alternatively, define MC repository
  #usernameEnvVar : 'GITHUB_USER',                    // Environment variable containing the username used for authentication
  #passwordEnvVar : 'GITHUB_TOKEN',                   // Environment variable containing the password used for authentication
  #useLatestMetacello : true,                         // Upgrade Metacello before loading
  #version : '1.0.0'                                  // Define MC version (for MC Configurations only)
  #registerInIceberg : true                           // Pharo Only | Register the tested repository in Iceberg
}

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
  #usernameEnvVar : 'USERNAME_VAR',                   // Environment variable containing the username used for authentication
  #passwordEnvVar : 'PASSWORD_VAR',                   // Environment variable containing the password used for authentication
  #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
  #usernameEnvVar : 'USERNAME_VAR',                   // Environment variable containing the username used for authentication
  #passwordEnvVar : 'PASSWORD_VAR',                   // Environment variable containing the password used for authentication
  #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, and Pharo 6 or later)
    #failOnSCIDeprecationWarnings : false, // Fail if a deprecated smalltalkCI API is used
    #failOnZeroTests : false, // Pass builds that did not run any tests
    #hidePassingTests : true, // Hide passing tests when printing to stdout
    #serializeError: false // (default: true) Disable serialization of failing test case (e.g. with Fuel in Pharo)
  }
}

Coverage Testing

See COVERAGE.md.

Custom Scripts

It is possible to run custom scripts before and after the loading and testing phases (preLoading, postLoading, preTesting, postTesting). smalltalkCI can file in single files, lists of files, and SCICustomScripts which can be used to only run certain scripts on certain platforms.

SmalltalkCISpec {
  #preLoading : 'scripts/preLoading.st',
  #loading : ...,
  #postLoading : [
    'scripts/postLoading1.st',
    'scripts/postLoading2.st'
  ],
  #preTesting : SCICustomScript {
    #path : 'scripts/preTesting.st',
    #platforms : [ #squeak, #pharo, #gemstone ]
  },
  #testing : ...,
  #postTesting : [
    SCICustomScript {
      #path : 'scripts/postTestingSqueak.st',
      #platforms : [ #squeak ]
    },
    SCICustomScript {
      #path : 'scripts/postTestingPharo.st',
      #platforms : [ #pharo ]
    }
  ]
}

Command Line Options

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

USAGE: bin/smalltalkci [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.
  --image             Custom image for build (Squeak/Pharo).
  --install           Install symlink to this smalltalkCI instance.
  --print-env         Print all environment variables used by smalltalkCI
  --no-color          Disable colored output
  --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'.
  --vm                Custom VM for build (Squeak/Pharo).

EXAMPLE:
  bin/smalltalkci -s "Squeak64-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 a supported CI platform. This helps 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

Travis Timeouts

Jobs on Travis CI timeout if they don't produce output for more than 10 minutes. In the 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:

• @ba-st: Buoy, RenoirSt, Willow.
• @Cormas: Cormas.
• @dalehenrich: obex, tode.
• @DuneSt: Heimdall, MaterialDesignLite, PrismCodeDisplayer.
• @HPI-BP2015H: squeak-parable.
• @hpi-swa: animations, Ohm-S, signals, Sandblocks, Squot, vivide, widgets.
• @hpi-swa-lab: Babylonian Programming/Smalltalk, Squeak by Example, Squeak Inbox Talk.
• @HPI-SWA-Teaching: Algernon-Launcher, AutoTDD, Koans, Morphic Testing Framework, Poppy Print, SpreadSheetTool, TelegramClient, SwaLint.
• @LinqLover: create-image, SimulationStudio, TelegramBot, XmasDecorations.
• @marianopeck: OSSubprocess, FFICHeaderExtractor.
• @Metacello: metacello.
• @newapplesho: aws-sdk-smalltalk, elasticsearch-smalltalk, mixpanel-smalltalk, OpenExchangeRates, pardot-smalltalk, salesforce-smalltalk, sendgrid-smalltalk, twilio-smalltalk.
• @ObjectProfile: Roassal2.
• @OpenPonk: borm-editor, borm-model, class-editor, demo-editor, fsm-editor.
• @OpenSmalltalk: opensmalltalk-vm.
• @pharo-project: pharo-project-proposals.
• @PolyMathOrg: PolyMath.
• @SeasideSt: Grease, Parasol, Seaside.
• @SergeStinckwich: PlayerST.
• @squeak-smalltalk: squeak-app, squeak-filesystem, squeak-ston, squeak-tonel.
• @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.