A modern smoke testing framework designed to test external systems with BDD support through Cucumber.js. Built with TypeScript best practices and deployable as an AWS Lambda function, this framework enables comprehensive smoke testing against any target system either locally or in the cloud.

• 📖 Docs Index — Start here
• Overview
• Getting Started
• User Guide
• Reference
• Development

• Overview
• Main Features
• Project Structure
• Quick Start
• Usage
• Available Scripts
• Troubleshooting
• Copyright & License

Smoker is a specialized framework for conducting smoke tests against external target systems using Behavior-Driven Development (BDD) principles. It implements the Cucumber.js World pattern for state management between test steps and provides a flexible configuration system that supports multiple sources including JSON files, AWS S3, SSM parameters, and environment variables.

The framework is designed to validate that external systems are functioning correctly by running automated tests that check critical functionality without deep integration testing. It's particularly useful for:

• API Health Checks: Validating REST endpoints and service availability
• System Integration Validation: Ensuring connected systems communicate properly
• Deployment Verification: Confirming successful deployments in various environments
• Continuous Monitoring: Running periodic health checks in production environments

Write tests in human-readable Gherkin syntax with full Cucumber.js support. Create comprehensive test scenarios that are easy to understand and maintain. Learn more in the Testing.

Pre-built clients for REST APIs, MQTT messaging, Kafka, and comprehensive AWS services (S3, SSM, SQS, CloudWatch, Kinesis). Extensible architecture allows easy addition of custom clients. Complete documentation available in the Service Clients.

• JSON Configuration Files: Local and remote configuration files
• AWS S3 Integration: Load configurations from S3 buckets
• AWS SSM Parameters: Secure parameter management with automatic resolution
• Environment Variables: Runtime configuration override capabilities
• Deep Merging: Intelligent configuration merging with priority ordering

Deploy as AWS Lambda function with comprehensive AWS service support. Includes CloudWatch metrics publishing, S3 report storage, and seamless integration with AWS infrastructure.

Full type safety throughout the framework with comprehensive interfaces, generics, and compile-time validation.

Easy to extend with new service clients, custom step definitions, and additional functionality through well-defined interfaces and patterns.

smoker/
├── src/
│   ├── clients/                   # Service client implementations
│   │   ├── aws/                   # AWS service clients (e.g., S3, SSM, SQS)
│   │   ├── core/                  # Core client interfaces and base classes
│   │   └── http/                  # HTTP clients (REST)
│   ├── lib/                       # Utilities (dates, retry, etc.)
│   ├── support/                   # Integration and config helpers
│   ├── errors/                    # Error classes and codes
│   └── world/                     # Cucumber.js World implementation
├── features/                      # Cucumber feature files and steps
│   ├── step_definitions/
│   └── *.feature
├── docs/                          # Documentation site (new IA)
│   ├── index.md                   # Docs landing page
│   ├── overview/
│   ├── getting-started/
│   ├── usage/
│   ├── reference/
│   ├── development/
│   ├── troubleshooting/
│   └── meta/
├── test/                          # Unit tests (Vitest)
├── cdk/                           # AWS CDK stack and scripts
├── package.json                   # Node.js dependencies and scripts
├── tsconfig.json                  # TypeScript configuration
└── README.md                      # Project overview (this file)

• Node.js 22+ and npm
• AWS CLI configured (for AWS features)
• TypeScript knowledge recommended

1. Clone the repository:

   git clone https://github.com/fabianopinto/smoker.git
   cd smoker

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Run example tests:

   npm start

1. Create a feature file in features/:

   Feature: API Health Check
     Scenario: Verify API is responding
       Given I have a REST client configured for "https://api.example.com"
       When I send a GET request to "/health"
       Then the response status should be 200

2. Run your test:

   npm start -- --paths "dist/features/your-test.feature"

For comprehensive usage instructions including configuration management, AWS deployment, and advanced features, see the User Guide:

• Configuration
• Running Locally
• Running in AWS
• Reporting & Monitoring

# Run all tests
npm start

# Run specific feature files
npm start -- --paths "dist/features/api/**/*.feature"

# Run tests with specific tags
npm start -- --tags "@smoke and not @wip"

# Run with custom configuration
npm start -- --config config/production.json

JSON Configuration:

{
  "api": {
    "baseUrl": "https://api.example.com",
    "timeout": 5000,
    "authToken": "ssm:/app/api-token"
  },
  "cert": {
    "pem_file": "s3://my-test-bucket/api-cert.pem"
  }
}

Environment Variables:

export LOG_LEVEL=debug

# Type-check and build
npm run check && npm run build

# Run specific test suites
npm test -- --testNamePattern="ConfigFactory"

# Generate coverage report
npm run test:coverage

# Lint and format code
npm run lint && npm run format

Use Vitest in run mode (non-watch) and prefer running tests individually to avoid timeouts:

# All tests
npx vitest run

# Single file
npx vitest run test/clients/aws/aws-cloudwatch-metrics.test.ts

# By test name pattern
npx vitest run --testNamePattern="RestClient"

Build Errors:

# Clear build cache and rebuild
npm run clean && npm run build

Test Failures:

# Run tests with verbose output
npm test -- --verbose

# Run specific failing test
npm test -- --testNamePattern="failing test name"

Configuration Issues:

# Validate configuration with debug logging
npm start -- --logLevel debug

AWS Permission Issues:

# Verify AWS credentials
aws sts get-caller-identity

# Test SSM parameter access
aws ssm get-parameter --name "/your/parameter/name"

Enable debug logging for detailed troubleshooting:

# Environment variable
export LOG_LEVEL=debug

# Command line option
npm start -- --logLevel debug

# Configuration file
{
  "logLevel": "debug"
}

1. Check the documentation:

   • Getting Started for first steps
   • Testing for framework tests and standards
   • Service Clients for client-specific details

2. Review example tests in the features/ directory

3. Check the issue tracker on GitHub for known issues

4. Enable debug logging to get detailed error information

Copyright (c) 2025 Fabiano Pinto

This project is licensed under the ISC License. See the LICENSE file for details.

This project uses several open-source libraries. See individual package licenses for details:

• Cucumber.js: MIT License
• AWS SDK: Apache License 2.0
• TypeScript: Apache License 2.0
• Other dependencies: See package.json for complete list

Ready to start testing? Check out Getting Started to create your first smoke test suite!