https://github.com/itsfarseen/shellspec
Testing framework for shell commands with declarative syntax.
https://github.com/itsfarseen/shellspec
Last synced: 6 months ago
JSON representation
Testing framework for shell commands with declarative syntax.
- Host: GitHub
- URL: https://github.com/itsfarseen/shellspec
- Owner: itsfarseen
- License: mit
- Created: 2025-09-09T12:16:28.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-14T10:02:32.000Z (10 months ago)
- Last Synced: 2025-10-11T14:34:45.305Z (10 months ago)
- Language: Python
- Homepage:
- Size: 775 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/itsfarseen/shellspec/actions/workflows/ci.yml)
# ShellSpec
Testing framework for shell commands with declarative syntax.
## Features
- Test shell commands with expected success/failure
- Interactive command testing with pexpect
- Variable storage and manipulation
- File operations and content verification
- Reusable test snippets
- Isolated test environments
## Installation
Requirements: Python 3.7+, pexpect library
```bash
pip install pexpect
chmod +x shellspec.py
```
## Usage
```bash
# Run all tests
./shellspec.py mytests.spec
# Run specific test by number or name
./shellspec.py mytests.spec --test 1
./shellspec.py mytests.spec --test "file operations"
# Show command output
./shellspec.py mytests.spec --verbose
```
## Writing Tests
For complete syntax documentation, see [SYNTAX.md](SYNTAX.md).
For a quick reference, see the [cheatsheet](shellspec-cheatsheet.txt).
### Basic Test Structure
```
> Test case name
$. command args # Run command expecting success
?. stdout "expected" # Assert stdout contains "expected"
```
## Demos and Examples
**Calculator**
See the [calculator_spec.txt](examples/calculator_spec.txt) for the test implementation.
**File Processor**
See the [file_processor_spec.txt](examples/file_processor_spec.txt) for the test implementation.
**Interactive Calculator**
See the [interactive_calculator_spec.txt](examples/interactive_calculator_spec.txt) for the test implementation.
## Configuration
### Command Aliases
ShellSpec allows you to define aliases for commands to simplify testing or provide custom paths. Edit the `COMMAND_ALIASES` dictionary in `shellspec.py`:
```python
COMMAND_ALIASES = {
"myapp": "../path/to/myapp",
"python3": "/usr/bin/python3",
}
```
Commands not found in the aliases dictionary will be executed directly as system commands.
### Timeout Settings
The default timeout for shell commands is 30 seconds. Modify `SHELL_TIMEOUT` in `shellspec.py` to change this.
## Documentation
- **[SYNTAX.md](SYNTAX.md)** - Complete syntax reference with examples
- **[shellspec-cheatsheet.txt](shellspec-cheatsheet.txt)** - Quick reference for all commands
## License
MIT License - see [LICENSE](LICENSE) for details.
## Related Projects
ShellSpec was originally developed as part of the age-store project for testing command-line encryption tools. It has been extracted into its own project for broader use.