SpruceCLI
A World Class, Open Source Testing Framework for Typescript and Visual Studio Code.
Features
Rediculously Easy to Use:
- Simple commands with helpful prompts.
- No “starter projects” or “boilerplates” to manage.
Beatiful Test Runner: “There is nothing quite like it.”
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.
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.
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.
- Use
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.
Build Watcher: Automatically build your code on every save.
- Tests are run against built code (not using
ts-node
), making them much faster.
- Tests are run against built code (not using
Upgrader: Update all your dependencies in 1 go!
Errors:
- Error Codes: Utilize the
SpruceError
to throw errors withCodes
. - Error Assertions: Assert errors against error codes and error metadata.
- Error Codes: Utilize the
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:
- 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. - Test Reporter: A totally custom built, beautiful test reporter that makes running tests enjoyable.
- 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:
- Linting:
VSCode
will format your code on save. This is done using customeslint
andprettier
configurations, following best practices. - Building:
VSCode
will automatically build your code on save. This is done usingtsc
and a customtsconfig.json
file. - Testing: The
Test Runner
is integrated right into the interface, making sure your tests are always visible.
Definitions
Concept | Description |
---|---|
Test File | Test files written in Typescript. Exports 1 default class. |
Test Class | The class that holds your tests. Extends on AbstractSpruceTest . |
@test Decorator | Used to define which methods are tests, importad as import { test } from @sprucelabs/test-utils |
assert | A utility class that holds the basic assertions, imported as import { assert } from @sprucelabs/test-utils . |
errorAssert | A utility class that enables you to assert against errors, imported as import { errorAssert } from @sprucelabs/test-utils . |
Test Runner | The Jest test runner. Actually runs the tests and streams results to the Test Reporter . |
Behavior Test | A test that asserts against the inputs and outputs of a higher order function. It is not concerned with the implementation (the details of the work being done). Behavior tests are preferred because they don’t break when you refactor your implementation. |
Implementation Test | A test that asserts against the implementation details of a lower oder function. Or, one that spies on a higher order function. Implementation tests are risky because they have to be reworked when your refactor. |
Installing
Homebrew
brew tap sprucelabsai-community/spruce
brew install spruce
Yarn or NPM
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
orImplementation
tests. If you are unsure, selectBehavioral
.
Note: You may be asked to install the
Skill Feature.
If you started by runningspruce create.module
, selectAlways Skip
. Installing this will turn your module into aSkill
that runs on theSpruce Platform
.
Node: You will be asked to select a base test class. Select
AbstractSpruceTest
to start.