Repository files navigation

Specron is a lightweight, open source, magic-free framework for testing smart contracts written inSolidity. The testing suite is built on top of theHayspec framework thus usingTypeScript is supported.

Specron provides development environment for the Ethereum blockchain and includes useful tools which enable developers to easily write tests for smart contracts.

The source code is available onGitHub where you can also find ourissue tracker.

Start by installing the Specron command-line tool.

$ npm install -g @specron/cli web3 solc

Specron depends on the latestweb3 andsolc packages, so make sure you have them globally installed. Specron also uses promises thus you need to usePromise polyfill when promises are not supported.

Specron automates the testing process of your Solidity code. It doesn't require you to install certain applications in order to get started.

The Specron interface is designed to fully support the power ofTypeScript when writing tests. It is magic-free which means you have a complete control and visibility of what the code does and how tests are executed. The testing flow should look familiar to any JavaScript or TypeScript developer.

Start by creating a new project folder.

$ mkdir myproject$cd myproject

Initialize the project and install the dependencies.

$ specron init$ npm install

Run tests to verify everything works as expected.

$ npmtest

The core test functionality is provided by the@specron/spec module which is automatically attached to your project at initialization. Here we explain some of the main framework features but please explore the source code to find out all the possibilities.

The framework provides aSpec class which holds basically the whole testing power. You start your test by creating an instance of that class.

import{Spec}from'@specron/spec';constspec=newSpec();

The Spec instance provides methods that you can use when writing tests. Most of the time you will use thetest method which performs the test you write.

spec.test('is true',async(ctx)=>{// promise | functionctx.true(true);});

There is also theskip method which prevents a test to be performed, and theonly method which includes itself into the test process but excludes all other tests.

Tests can be nested using thespec method.

constcolors=newSpec();...spec.spec('colors',colors);

The framework providesbefore andafter methods which are execute at the beginning and at the end of the spec case.

spec.before((stage)=>{// execute before all tests});...spec.after((stage)=>{// execute after all tests});

These methods have access to thestage of the spec instance. The stage is global to the whole spec stack which means that all settings are always preserved.

There are also thebeforeEach andafterEach methods which are triggered before and after each test. These methods have access to thecontext andstage of the spec. The context represents a copy of a stage and is preserved betweenbeforeEach,test andafterEach methods. This allows for testing atomic tests where a fresh context is always created for each test.

spec.beforeEach((context,stage)=>{// execute before all tests});...spec.afterEach((context,stage)=>{// execute after all tests});

Callback functions can be called multiple times and the execution will happen in a defined sequence.

Thecontext and thestage both provide a way toset andget values with proper TypeScript types.

interfaceData{id:number;name:string;}constspec=newSpec<Data>();spec.beforeEach((ctx)=>{ctx.set('id',100);ctx.set('name','John');})spec.test('is John with id=100',(ctx)=>{constid=ctx.get('id');constname=ctx.get('name');ctx.is(id,100);ctx.is(name,'John');})

Values set inside thebefore andafter blocks are available to allspec methods. Values set in thebeforeEach andafterEach blocks are available only on the context stack of each test.

Stage and context both provide a series of different helper methods.

A very important method is thedeploy() method which deploys a contract to a local blockchain process in the background and returns a contract instance.

const{ instance, receipt}=awaitctx.deploy({src:'./contracts.json',contract:'Main',});

The@specron/cli module is automatically installed when you initialize the project. You can interact with the utility using thenpx specron command in your terminal.

To get a list of available features use the--help flag.

$ npx specron --help

Every test file must export thespec instance for the CLI to be able to detect the test.

exportdefaultspec;

Run thespecron test command to run tests. Customize the files search by using the--match flag.

$ npx specron test --match ./**/*.test.*

Install thets-node NPM package then use the--require flag to enableTypeScript support.

specron --require ts-node/register

Specron configuration options can be saved inside the package.json file under the thespecron key.

{"specron": {"compiler": {"build":"./build","match": ["./src/**/*.sol"      ],"severities": ["error","warning"      ],"evmVersion":"byzantium"    },"flattener": {"build":"./build","match": ["./src/**/*.sol"      ],"severities": ["error","warning"      ]    },"sandbox": {"port":8545,"host":"localhost"    },"test": {"server":true,"port":8545,"host":"localhost","match": ["./src/**/*.test.*"      ]    },"require": ["ts-node/register"    ]  }}

Note that these options can be overriden by providing CLI arguments.

For a full example of a Solidity contract repository including continuous integration using Travis and Specron, seehttps://github.com/xpepermint/specron-example.

Package	Description	Version
@specron/cli	Command-line interface.
@specron/compiler	Smart contracts compiler.
@specron/flattener	Smart contracts flattener.
@specron/init	Project structure initializer.
@specron/sandbox	Ethereum sandbox server.
@specron/spec	Core test suite.

SeeCONTRIBUTING.md for how to help out.

SeeLICENSE for details.