# osmo-python-tests

Various scripts that are mostly used for interacting with VTY/CTRL interfaces
of Osmocom programs.

## Installation

### Python user install directory

While discouraged by the python developers, the easiest way to make
osmo-python-tests always available for your user is installing to
`~/.local/lib/python3.*/site-packages/osmopy`:

```
$ pip3 install --user --break-system-packages .
```

### Virtual environment

If you prefer to have osmo-python-tests clearly separated, install to a venv:

```
$ python3 -m venv ~/.osmocom-venv
$ source ~/.osmocom-venv/bin/activate
$ pip3 install .
```

Keep in mind that you must run the source line again whenever you need to use
osmo-python-tests.

### Osmocom binary packages

If you run a Debian-based Linux distribution, you can alternatively enable the
[Osmocom binary repository](https://osmocom.org/projects/cellular-infrastructure/wiki/Binary_Packages)
and do a system-wide installation:

```
# apt install osmo-python-tests
```

## Usage

There are currently following scripts in this package:

* `osmotestconfig.py` - test that apps start/write with example configs
* `osmo_trap2cgi.py` - implementation of CGI <-> Ctrl proxy implemented on top of asyncio and aiohttp
* `osmo_rate_ctr2csv.py` - rate counter dumper on top of osmo\_ipa
* `osmo_interact_vty.py` - pipe stdin/stdout to a VTY session
* `osmo_interact_ctrl.py` - pipe stdin/stdout to a CTRL port
* `osmo_verify_transcript_vty.py` - VTY testing by VTY session screen dumps
* `osmo_verify_transcript_ctrl.py` - CTRL testing by CTRL session script files
* `osmodumpdoc.py` - dump documentation, superseded by `osmo_interact_vty.py -X`
* `osmotestvty.py` - test vty operations, superseded by `osmo_verify_transcript_vty.py`

Some of these scripts import a project-specific `osmoappdesc.py`, which
provides information about the available apps, configs, vty ports, etc. and is
provided by other source trees (like osmo-bsc.git, osmo-msc.git, ...).

Run the scripts with `osmoappdesc.py` in the current directory (preferred) or
with `-p <the directory containing osmoappdesc.py>`. Remember that
`osmoappdesc.py` may contain relative paths.

### Example

Build osmo-ns-dummy from libosmocore:

```
$ cd libosmocore
$ autoreconf -fi
$ ./configure
$ make
```

Enter the directory with `osmoappdesc.py` and run a test script:

```
$ cd tests/gb
$ osmotestconfig.py -w .
```

## Libraries

* `osmopy/osmoutil.py` - code that's shared between the scripts
* `osmopy/osmo_ipa.py` - generic implementation of IPA and Ctrl protocols in python
* `osmopy/trap_helper.py` - generic Trap class and related helpers used by `soap.py` and `ctrl2cgi.py`
* `osmopy/osmo_interact/{vty,ctrl}.py` - general interactions with VTY and CTRL ports
* `osmopy/obscvty.py` - connect to a vty, superseded by `osmo_interact/vty.py`

`obscvty.py` may be of general use. `osmoutil.py` probably isn't.