Segment Local Functions (SLF == Sloth)

Enable development and testing of Segment functions locally and in your choice of TypeScript or JavaScript. Features

• Develop in your choice of TypeScript or JavaScript
• When choosing TypeScript, enable fully typed development against tracking plans
• Debug your functions from within your IDE, including initiating source-function runs from external URL calls (to test against your actual service providers), or initiating destination-function runs from the Segment UI (to enable easy testing with events collected by Segment)
• Test your functions locally (for automated unit/functional testing),
• Deployment of functions

Requirements

• Node v12 or above
• AWS-SAM ()
• (optional) TypeScript
• (optional) Nodemon, for automatically updating debug/test environments on code change
• (optional) Ngrok, for opening up a URL to your local machine so your function can be called by your service whilst tested locally.
• (optional) Mocha, for running the tests (this is the default framework used, but any testing framework will work)

Quick Start

Install the command-line utility:

npm i -g segment-local-functions

Create a new folder for your new function

mkdir my-test-function
cd my-test-function

Initalise a new project (and see the Detailed Usage Guide below for details on the init wizard)

sloth init

Edit your function src/function.js (for JavaScript), or src/function.ts (for TypeScript)

Edit your tests src/tests/test.js (for JavaScript), or src/tests/test.ts (for TypeScript)

If using TypeScript, compile your code

tsc -p .

Launch the local instance ready for debugging your code (you may want to run this in a new terminal as it keeps control whilst it is running)

sloth debug

If using JavaScript, run your tests as follows:

mocha src/tests/test.js

Or if using TypeScript, run your tests as follows:

mocha out/tests/test.js

From within your IDE, launch a new debug session. If using Visual Studio Code, a debug launcher is set-up. Go to Debug and select "Debug Function".

If developing a source function, test your function directly against your provider. To do this, launch the Grok-tunnel:

sloth grok

Take note of the URL returned, and point your service to call to this endpoint.

If developing a destination function, test your function via the Segment UI, to enable testing against events collected within your workspace. Again, you'll need the Grok-tunnel (if not already running):

sloth grok

Go to your Segment Workspace, under Catalog -> Functions you'll see your function listed. Go into edit and run and events will be proxied to your local instance for debugging. Note: The Segment function will probably time-out and "fail" because it isn't actually running any code (it's just being used to forward events); this is expected behaviour

Finally, to run tests locally for automated testing, kill any currently running sloth debug instance, and instead launch a test instance:

sloth test

Now, when you run your tests, you won't have to launch a debug session from your IDE; instead everything will just run immediately.

When ready to deploy your code run:

sloth deploy

Or, if you choose the GitHub workflow integration, enable the actions in your target repository.

Finally, if you choose TypeScript and also provided a tracking plan to develop against, you can update the definition against the latest tracking plan by running

sloth sync_tp

Detailed Usage Guide

TODO

Not yet implemented

• Function parameters