SpruceCLI

A World Class, Open Source Testing Framework for Typescript and Visual Studio Code.

Features

1. Rediculously Easy to Use:

   • Simple commands with helpful prompts.
   • No “starter projects” or “boilerplates” to manage.

2. Beatiful Test Runner: “There is nothing quite like it.”

3. Multiple Watch Modes:

   • Smart: Auto-filters to tests that have changed and/or failed. After a successful run, it will run all tests.

   • Standard: Keeps current filter on changes. If no filter is set, it runs all tests on every change.

4. Class Based Test Files:

   • Easy scope management: No more managing multiple levels of scope. Just use this to access the test’s state.

   • Easily Extend Test Classes: Create a parent test class to hold helpful assertions, setup methods, fixtures, etc.

5. Decorator Based:

   • Use @test() to define which Class methods are tests.
   • Parameterized Tests: Use the @test() decorator with arguments to run the same test with different input.

6. Tight VSCode Integration:

   • Formatting: Beatuifully format your code on every Save.
   • Test Explorer: View and run tests from the sidebar.
   • Debugging: Debug tests with breakpoints.

7. Build Watcher: Automatically build your code on every save.

   • Tests are run against built code (not using ts-node), making them much faster.

8. Upgrader: Update all your dependencies in 1 go!

9. Errors:

   • Error Codes: Utilize the SpruceError to throw errors with Codes.
   • Error Assertions: Assert errors against error codes and error metadata.

What is it?

The SpruceCLI is a command line tool that enables developers to “Build Great Software Fast.” The testing elements of the cli are actually just a small part of it’s overall capabilities.

For this documentation, we will focus on the testing and VSCode integration aspects of the cli.

Testing

The testing framework is comprised of 3 main parts:

1. Test Runner: The test runner is built ontop of Jest. This is managed behind-the-scenes by the cli, so you don’t have to deal with any of it’s complexities.
2. Test Reporter: A totally custom built, beautiful test reporter that makes running tests enjoyable.
3. Assertion Library: A custom built assertion library that is designed to be easy to intuitive and reliable. No global objects, no magic, just simple assertions.

VSCode Integration

Running commands manually is fine enough, but nothing beats having all the tooling you need “just work” right in your IDE.

There are 3 main parts to the VSCode integration:

1. Linting: VSCode will format your code on save. This is done using custom eslint and prettier configurations, following best practices.
2. Building: VSCode will automatically build your code on save. This is done using tsc and a custom tsconfig.json file.
3. Testing: The Test Runner is integrated right into the interface, making sure your tests are always visible.

Definitions

Installing

yarn global add @sprucelabs/spruce-cli

npm install -g @sprucelabs/spruce-cli

Starting a New Module

When you are starting a node module from scratch, you can use spruce to set you up with a fully functioning Typescript project. This will not install the Test tools, but will leave you with a fully functioning Typescript node module with linting and building:

spruce create.module [destination]

Note: If you do not supply a destination, it will default to the current directory.

Note: After the command is done, follow the instructions printed in the summary.

Adding to an Existing Module

If you already have a Typescript module running, you can add Spruce pretty easily:

Setting up vscode

cd path/to/your/module
spruce setup.vscode

Your First Test

After you have created your new module or setup an existing one, you can generate your first test!

Once vscode is loaded up, you can run the following:

spruce create.test

Note: You’ll be asked if you want to select Behavioral or Implementation tests. If you are unsure, select Behavioral.

Note: You may be asked to install the Skill Feature. If you started by running spruce create.module, select Always Skip. Installing this will turn your module into a Skill that runs on the Spruce Platform.

Node: You will be asked to select a base test class. Select AbstractSpruceTest to start.

Command Reference

Use --help on any command for detailed options (e.g., spruce test --help).

Authentication

Skills

Events & Listeners

Schemas

Stores

Views

Testing

Errors

Permissions

Conversations

AI & Agents

Logging

Projects & Modules

Environment

Working with Skills

Creating a Skill

spruce create.skill my-skill
cd my-skill

You’ll be prompted to configure your skill. After creation, follow the printed instructions to complete setup.

Registering with Mercury

Before your skill can communicate with other skills and the platform, you need to register it:

spruce login
spruce register.skill

This creates a .env file with your skill’s credentials. Keep this file secure and never commit it to version control.

Booting Your Skill

spruce boot

This starts your skill and connects it to Mercury. Your event listeners will begin receiving events.

Installing at an Organization

To make your skill available to an organization:

spruce install.skill

You’ll be prompted to select which organization to install at.

Adding Dependencies

If your skill needs to communicate with another skill:

spruce add.dependency other-skill-namespace

This pulls in the event contracts from the dependency so you can emit and listen to its events.

Something Missing?