Introduction
Cucumber for Tezos Cucumis enables developers to write behavior-driven tests for Tezos smart contracts using plain English scenarios. This guide shows you how to set up, write, and execute Cucumber tests on the Tezos blockchain in under 30 minutes.
Key Takeaways
- Cucumber for Tezos uses Gherkin syntax to define contract behavior in human-readable format
- Installation requires Node.js, Docker, and the Cucumber CLI alongside Tezos tooling
- Test scenarios map directly to Michelson contract entrypoints
- The framework supports both positive and negative test cases for contract validation
- Integration with CI/CD pipelines requires specific environment configuration
What is Cucumber for Tezos Cucumis
Cucumber for Tezos Cucumis is a testing framework that bridges BDD (Behavior-Driven Development) with Tezos smart contract development. The tool interprets Gherkin feature files and translates them into Michelson contract calls through the Tezos RPC layer.
The framework consists of three core components: the Gherkin parser, the step definition library, and the Tezos client adapter. Developers write scenarios in English-like syntax while the framework handles RPC communication, type conversions, and result validation automatically.
Why Cucumber for Tezos Matters
Smart contract security demands rigorous testing before mainnet deployment. Cucumber bridges the gap between technical developers and stakeholders by allowing anyone to read and validate contract behavior specifications.
Traditional unit tests require programming knowledge to understand. Cucumber scenarios serve as executable documentation that non-technical team members can review and approve. This transparency reduces miscommunication and accelerates stakeholder sign-off on contract requirements.
How Cucumber for Tezos Works
Architecture Overview
The testing workflow follows a structured four-layer process that transforms human-readable scenarios into blockchain operations.
Mechanism Breakdown
Layer 1 – Feature Parsing: Cucumber reads .feature files containing Gherkin keywords (Given, When, Then) and extracts step definitions.
Layer 2 – Step Mapping: JavaScript step definitions match textual steps to executable functions that interact with the Tezos client.
Layer 3 – RPC Communication: The Tezos client adapter constructs proper RPC calls to the sandbox or testnet node, including origination, parameter injection, and view calls.
Layer 4 – Assertion Validation: Expected outcomes compare against actual contract storage and operation results using Chai or similar assertion libraries.
Core Execution Formula
Scenario Execution Time = (Network Latency × Call Count) + (Storage Read × Gas Estimation) + Assertion Overhead
This formula helps developers estimate test duration and optimize test suites for CI/CD performance.
Used in Practice
To implement your first Cucumber test for Tezos, install the required dependencies via npm. Initialize the project structure with feature files in the features directory and step definitions in step_definitions.
Write a simple transfer scenario that validates a FA2 token contract. Define a Given step that originates the contract, a When step that executes a transfer, and a Then step that verifies balance changes in storage.
Execute tests against a local Tezos sandbox using the command “cucumber-js –world-parameters {tezosNetwork: ‘sandbox’}”. The framework handles account management, token origination, and storage state verification automatically.
Risks and Limitations
Cucumber for Tezos operates against test environments only. You cannot execute scenarios against mainnet directly through the framework. All contract interactions require proper test token funding and sandbox configuration.
Gas estimation accuracy varies between sandbox and mainnet conditions. Complex contracts may exhibit different execution costs in production. Always validate gas consumption through mainnet simulation before deployment.
The framework lacks built-in support for private key management. Developers must implement secure secret handling through environment variables or dedicated secrets managers to avoid exposing sensitive credentials.
Cucumber vs Unit Testing for Tezos
Cucumber for Tezos: Focuses on behavior validation from a user perspective. Scenarios describe business logic and contract interactions in natural language. Ideal for acceptance testing and stakeholder communication.
Tezos unit tests (SmartPy/Taquito): Test individual functions and internal logic at the code level. Provide granular control over test parameters and support edge case exploration. Better suited for developer-driven debugging and coverage analysis.
Complementary use: Most teams deploy both approaches. Unit tests catch internal errors during development while Cucumber scenarios validate end-to-end behavior before deployment.
What to Watch
Monitor your test suite execution time as contract complexity grows. Each scenario requiring contract origination adds significant overhead. Consider using shared contract instances across scenarios to reduce runtime.
Validate Gherkin syntax carefully before execution. Cucumber’s error messages for syntax errors can be cryptic and delay debugging. Use the –dry-run flag to validate feature files without full execution.
Track test coverage by mapping scenarios to contract entrypoints. Ensure critical functions have both positive and negative test coverage. Document entrypoints without Cucumber scenarios in your testing strategy.
Frequently Asked Questions
What programming languages support Cucumber for Tezos?
The primary implementation uses JavaScript with the cucumber-js library. Community implementations exist for Python (behave) and Ruby, though JavaScript offers the most mature Tezos integration through Taquito.
Can I test existing deployed contracts with Cucumber?
Yes, scenarios can target already-originated contracts by specifying the contract address. You need the contract’s storage type definition to construct proper parameter encodings for testing.
How do I handle test token funding in CI environments?
Configure faucet accounts or use a test network with built-in faucet functionality. Store private keys in CI secrets and inject them as environment variables during test execution.
Does Cucumber support view-entrypoints and callbacks?
Current implementations focus on entrypoints that modify storage. View operations require separate HTTP client calls outside the standard Cucumber step definitions. Some community extensions address this limitation.
What is the recommended project structure for Tezos Cucumber tests?
Organize feature files by contract type and step definitions by functional domain. Keep feature files close to their corresponding contract source code in the repository structure for maintainability.
How does gas estimation work in test scenarios?
Cucumber for Tezos uses the node’s gas estimation RPC before executing each operation. Sandbox environments may return different estimates than mainnet, requiring validation runs before production deployment.
Can non-developers write Cucumber scenarios?
Yes, the Gherkin syntax intentionally uses plain English keywords. Business analysts and QA engineers can author scenarios without programming knowledge, though step definition updates require developer involvement.
What Tezos test networks work with this framework?
The framework supports Hangzhou, Ithaca, and earlier testnets through version-matched Tezos client binaries. Always align your Tezos client version with the target network protocol.