Skip to main content

A command line program test helper

Project description

Aurornis - A command line program test helper

Coverage Status

Aurornis is a small, yet powerful library designed to help testing command line programs. The name is a reference to the aurornis xui, a prehistoric bird that lived 10 million years ago.

Installation

Aurornis is available in PyPI, so all you need is to install it with PIP:

pip install --user aurornis

If you are using Pipenv or Poetry, it is recommended to install it as a development dependency:

pipenv install --dev aurornis
poetry add --dev aurornis

Important note: this library has not been tested on a production environment. For security reasons, it recommended to use it for development tests only. This might evolve in the future.

Main features

  • One simple function: give it the command, and it will take care of all the complexity for you
  • Supports the standard input, output and error
  • Computes the execution time of the command, so you can test its global performance directly
  • Provides a way to clean the colors to make testing simpler (with native support of the NO_COLOR standard)
  • Supports Linux, macOS and Windows. Probably also works on FreeBSD.

Basic usage

Aurornis provides a package with only one function to run a command, that returns an object with the result of the command:

import aurornis

command_result = aurornis.run(["ls", "-la", "/"])
# <CommandResult command="ls -la /" return_code=0 stdout="total 68 ..." stderr="">

For better security and reproducibility, the environment variables of your system are not reproduced, with the exception of $PATH on UNIX and SystemRoot on Windows.

If you need to specify environment variables (or even overwrite some of them) before you run the command, add them to the run function:

import aurornis

command_result = aurornis.run(["env"], environment={"HOME": "/home/deuchnord"})

By default, the LANG environment variable (used for internationalization) is reset to C (default system language, commonly English). You can change it if you want to test with another locale.

Once you get the result, all you need to do is to use your favorite unit test framework to check it returned what you expected it to return:

import aurornis
import unittest

class CommandTest(unittest.TestCase):
    def test_ls_home(self):
        command_result = aurornis.run(["ls", "-l", "$HOME"], environment={"HOME": "/home/deuchnord"})
        # You can check quickly the command was successful:
        self.assertTrue(command_result.successful)
        # Or if you expected a more specific return value:
        self.assertEqual(2, command_result.return_code) # ls returns 2 if the file does not exist
        
        # Then, check the text returned in standard output and standard error:
        self.assertEqual("""total 6
drwxr-xr-x 1 deuchnord deuchnord 40 27 May 13:19 Desktop
drwxr-xr-x 1 deuchnord deuchnord 40 14 Oct 18:08 Documents
drwxr-xr-x 1 deuchnord deuchnord 40  1 Sep 16:52 Downloads
drwxr-xr-x 1 deuchnord deuchnord 40 29 Sep 09:11 Pictures
drwxr-xr-x 1 deuchnord deuchnord 40 11 Jun  2020 Music
drwxr-xr-x 1 deuchnord deuchnord 40 10 Nov 11:32 Videos""", command_result.stdout)
        self.assertEqual("", command_result.stderr)

If your command returns colors in your standard output or standard error, you can ask Aurornis to automatically remove them:

import aurornis

aurornis.run(["echo", "-e", r'\e[0;32mHello World!\e[0m'], remove_colors=True)

This option also automatically sets the standard NO_COLOR environment variable. If your application shows colors, you may want to handle this environment variable to facilitate their deactivation by end users.

FAQ/Troubleshooting

How to handle correctly the return lines when my tests are executed on both Windows and non-Windows systems?

The run() function provides a way to handle it for you. Just set the normalize_carriage_return argument to True, and any \r\n will be replaced with \n. This will become the default behavior in the version 2.0.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aurornis-1.6.0.tar.gz (16.4 kB view details)

Uploaded Source

Built Distribution

aurornis-1.6.0-py3-none-any.whl (17.8 kB view details)

Uploaded Python 3

File details

Details for the file aurornis-1.6.0.tar.gz.

File metadata

  • Download URL: aurornis-1.6.0.tar.gz
  • Upload date:
  • Size: 16.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.13.3 Linux/6.11.0-1015-azure

File hashes

Hashes for aurornis-1.6.0.tar.gz
Algorithm Hash digest
SHA256 3b86689370fdf17f63f32db56795234923a031c783cf7a47b0578093cc26b5ee
MD5 594196a3ee6504154dd55781fde4693c
BLAKE2b-256 6ca83e55c16e569d62b68e614abd3b630e7bacd7356422c0a8249409d4607a36

See more details on using hashes here.

File details

Details for the file aurornis-1.6.0-py3-none-any.whl.

File metadata

  • Download URL: aurornis-1.6.0-py3-none-any.whl
  • Upload date:
  • Size: 17.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.13.3 Linux/6.11.0-1015-azure

File hashes

Hashes for aurornis-1.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 457ff4b8b3b0f1f16b434071c267a706bb96a23e5ada37f611f3a6520536e5ea
MD5 040e232e52b2966fb91fa46d4894cc27
BLAKE2b-256 fc8bf7d6fdd241d43630a97ad68916ba820c0e45d8cb2b599dbda3413ddc5117

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page