github.com/Comcast/plax@v0.8.32/README.md (about)

     1  # Plax: an engine for testing messaging systems
     2  
     3  [![Go Reference](https://pkg.go.dev/badge/github.com/Comcast/plax.svg)](https://pkg.go.dev/github.com/Comcast/plax)
     4  [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)
     5  [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
     6  
     7  
     8  > And with reference to the narrative of events, far from permitting
     9  > myself to derive it from the first source that came to hand, I did
    10  > not even trust my own impressions, but it rests partly on what I saw
    11  > myself, partly on what others saw for me, **the accuracy of the
    12  > report being always tried by the most severe and detailed tests
    13  > possible**.
    14  
    15  -- [Thucydides, _The History of the Peloponnesian
    16  War_](http://classics.mit.edu/Thucydides/pelopwar.1.first.html)
    17  
    18  
    19  ## Summary
    20  
    21  Plax is a test automation engine for messaging systems.  This engine
    22  is [designed](chans) to perform integrated testing of MQTT messaging,
    23  Kinesis streams, SNS traffic, SQS [trafic](demos/sqs.yaml), Kafka I/O,
    24  HTTP APIs, [subprocesses](demos/shell.yaml), mobile
    25  [apps](demos/webdriver.yaml) (via
    26  [WebDriver](https://www.w3.org/TR/webdriver/)), and more.
    27  
    28  An author of a test specifies a sequence of input and expected outputs
    29  over a set of channels that are connected to external services.
    30  Execution of the test verifies that the expected output occurred.
    31  
    32  ## Automated Build Status
    33  [![Test](https://github.com/Comcast/plax/actions/workflows/test.yml/badge.svg)](https://github.com/Comcast/plax/actions/workflows/test.yml)
    34  [![Tag](https://github.com/Comcast/plax/actions/workflows/tag.yml/badge.svg)](https://github.com/Comcast/plax/actions/workflows/tag.yml)
    35  [![Release](https://github.com/Comcast/plax/actions/workflows/release.yml/badge.svg)](https://github.com/Comcast/plax/actions/workflows/release.yml)
    36  
    37  ## Command-line tools in this repo
    38  
    39  1. [`plax`](cmd/plax): The test engine (and probably the reason you
    40     are here).  Documentation is [here](doc/manual.md).
    41  1. [`plaxrun`](cmd/plaxrun): Tool to run lots of Plax tests with
    42     various configurations.  Documentation is [here](doc/plaxrun.md).
    43  1. [`plaxsubst`](cmd/plaxsubst): Utility to test/use parameter
    44     substitution independently from other Plax functionality.  Related
    45     documenation is [here](subst/README.md).
    46  1. [`yamlincl`](cmd/yamlincl): YAML include processor utility.
    47     Documenation is [here](doc/manual.md#including-yaml-in-other-yaml).
    48  
    49  
    50  ## Usage
    51  
    52  Clone this repo and [install Go](https://golang.org/doc/install).
    53  Then:
    54  
    55  ```Shell
    56  (cd cmd/plax && go install)
    57  # Run one simple test.
    58  plax -test demos/mock.yaml -log debug
    59  # Run several tests.
    60  plax -dir demos -labels selftest
    61  ```
    62  
    63  That last command runs all the [example test specs](demos) that are
    64  labeled as `selftest`. [`basic.yaml`](demos/basic.yaml) is a good,
    65  small example of a test specification.
    66  
    67  ## Plugins
    68  1. [Octane plugin](doc/octane_plugin.md)
    69  
    70  ## The language
    71  
    72  See the [main documentation](doc/manual.md) and the [examples](demos).
    73  
    74  ## References
    75  
    76  1. [Plax manual](doc/manual.md) and the [`plaxrun`
    77     manual](doc/plaxrun.md)
    78  1. [Sheens pattern
    79     matching](https://github.com/Comcast/sheens#pattern-matching) and
    80     some
    81     [examples](https://github.com/Comcast/sheens/blob/master/match/match.md)
    82  1. [Sheens](https://github.com/Comcast/sheens), which could be
    83     [used](https://github.com/Comcast/sheens/tree/master/sio/siomq) to
    84     implement more complex tests and simulations
    85  1. [TCL "expect"](https://en.wikipedia.org/wiki/Expect)
    86