diff options
| -rw-r--r-- | README.md | 155 | ||||
| -rw-r--r-- | README.rst | 21 | ||||
| -rw-r--r-- | docs/config.rst | 30 | ||||
| -rw-r--r-- | docs/gettingstarted.rst | 42 | ||||
| -rw-r--r-- | docs/index.rst | 102 |
5 files changed, 118 insertions, 232 deletions
diff --git a/README.md b/README.md deleted file mode 100644 index 41cdc4b..0000000 --- a/README.md +++ /dev/null @@ -1,155 +0,0 @@ -# minishell test [](https://travis-ci.com/cacharle/minishell_test) [](https://pypi.org/project/minishell-test/) [](https://minishell-test.readthedocs.io) - -Test for the minishell project of school 42. - - - -## Installation - -### pip - -``` -$ pip3 install minishell-test -``` - -### Manual - -``` -$ git clone https://github.com/cacharle/minishell_test -$ cd minishell_test -$ pip3 install -e . -``` - -## Usage - -``` -$ minishell_test # In your project directory -$ python3 -m minishell_test # If you don't have ~/.brew/bin or ~/.local/bin in your PATH - -$ minishell_test --help -usage: minishell_test [-h] [-p PATH] [-l] [-t COMMAND] [-k] [-r BEGIN END] - [--show-range] [-x] [-v] [-b] [-n] [-m] [-g] - [suite [suite ...]] - -Test for the minishell project of school 42. - -positional arguments: - suite Test suites/group to run. - It tries to be smart and autocomplete the suite name - (e.g ./run int -> ./run preprocess/interpolation) - -optional arguments: - -h, --help show this help message and exit - -p PATH, --path PATH Path to minishell directory - -l, --list Print available test suites - -t COMMAND, --try-cmd COMMAND - Run a custom command like this test would - (the only environment variable passed to your executable are TERM and PATH) - -k, --check-leaks Run valgrind on tests (disable usual comparison with bash) - -r BEGIN END, --range BEGIN END - Range of test index to run (imply --show-index) - --show-range Show test index (useful with --range) - -x, --exit-first Exit on first fail - -v, --verbose Increase verbosity level (e.g -vv == 2) - -b, --bonus Enable bonus tests - -n, --no-bonus Disable bonus tests - -m, --make Make minishell and exit - -g, --pager After running the test, display the result in a pager of your choice - -Made by cacharle - https://cacharle.xyz -``` - -## Test compatibility - -Your executable **must** support the `-c` option which allow to pass command as string. - -```command -$ bash -c 'echo bonjour je suis' -bonjour je suis -$ ./minishell -c 'echo bonjour je suis' -bonjour je suis - -$ bash -c 'ls' -README.md test.sh -$ ./minishell -c 'ls' -README.md test.sh -``` - -With this setup `argv[2]` is what you would usually get in `line` from `get_next_line`. -This allows you to set the prompt to whatever you want. - -### Environement variables - -My test only gives the `PATH` and `TERM` environment variables to your minishell. -**Please check that your project still work with those settings before messaging me on Slack or creating an issue**. -You can test this quickly with the `-t` option (e.g `minishell_test -t 'echo bonjour`). - -## Bonus - -* Force the bonus tests with `$ minishell_test -b` -* Change the `BONUS` variable in [config.py](minishell_test/config.py) to True -* Set the environment variable `MINISHELL_TEST_BONUS` to `yes` - (e.g `echo 'export MINISHELL_TEST_BONUS=yes' >> ~/.zshrc`) - -## Memory leaks - -`$ minishell_test -k`, checkout the `--show-range`, `--range` and `-x` options to help -to select the tests to run since valgrind is really slow. - -## Don't check error messages - -If you don't want to copy bash syntax error message, -you can set the environment variable `MINISHELL_TEST_DONT_CHECK_ERROR_MESSAGE` to `yes`. -It will still test your exit status code but will discard any output on error tests. - -## Linux - -The tester will try to convert to output/status code of bash on Linux to the one on Mac. - ---- - -## Add new tests - -You can find the suites in the [minishell\_test/suites](minishell_test/suites) directory. - -### Add individual test - -In your suite function you can use the `test` function. With the following arguments: - -1. Command to be tested (output and status will be compared to bash) -2. A command to setup the sandbox directory where the tested command will be run -3. List of files to watch (the content of each file will be compared) - -```python -test("echo bonjour je suis") # simple command -test("cat < somefile", setup="echo file content > somefile") # setup -test("ls > somefile", setup="", files=["somefile"]) # watch a file -test("echo $A", exports={"A": "a"}) # export variables - # in the environment -test("echo bonjour", hook=lambda s: s.replace("o", "a")) # pass the shell output - # through a hook function - -test("cat < somefile > otherfile", - setup="echo file content > somefile", - files=["otherfile"]) -``` - -### Add Suite - -A test suite is a group of related tests. - -```python -@suite() # @suite(bonus=True) if it's a bonus suite -def suite_yoursuitename(test): - """ a description of the suite """ - test(...) - test(...) - test(...) -``` - ---- - -## Wildcard (or glob) - -There is a commented glob suite in [minishell\_test/suites/preprocess.py](minishell_test/suites/preprocess.py). -Good luck handling `*'.*'`. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..c593638 --- /dev/null +++ b/README.rst @@ -0,0 +1,21 @@ +minishell_test +============== + +.. image:: https://img.shields.io/pypi/pyversions/minishell-test + :alt: PyPI - Python Version + :target: https://pypi.org/project/minishell-test/ + +.. image:: https://readthedocs.org/projects/minishell-test/badge/?version=latest + :alt: Documentation + :target: https://minishell-test.readthedocs.io + +.. image:: https://api.travis-ci.com/cacharle/minishell_test.svg?branch=master + :alt: Build Status + :target: https://travis-ci.com/cacharle/minishell_test + +Test for 42 school's minishell project. + +.. image:: https://i.imgur.com/98xh2xY.gif + :alt: preview + +.. include:: docs/gettingstarted.rst diff --git a/docs/config.rst b/docs/config.rst index a8933d5..884cf9b 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -10,13 +10,11 @@ It looks for a ``minishell_test.cfg`` file in your project directory. Here is what the default configuration looks like: -.. code-block:: cfg - - .. include:: ../minishell_test/data/default.cfg +.. include:: ../minishell_test/data/default.cfg + :code: cfg -Format used for the configuration file: -https://docs.python.org/3/library/configparser.html#supported-ini-file-structure +The format of this file is described in more details `here <https://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_ Global ------ @@ -33,35 +31,35 @@ Global settings are defined under the ``minishell_test`` section: :type: true|false :default: false - Run the bonus tests + Run the bonus tests .. conf:: exec_name :type: PATH :default: minishell - Minishell executable name + Minishell executable name .. conf:: make :type: true|false :default: true - Run ``make`` in your project directory before the test + Run ``make`` in your project directory before the test .. conf:: pager :type: NAME :default: less - Pager to use when viewing your results + Pager to use when viewing your results .. conf:: log_path :type: PATH :default: minishell_test.log - File where to put the test results + File where to put the test results .. conf:: cache_path @@ -84,14 +82,14 @@ Shell settings are defined under the ``shell`` section: :type: LIST :default: rmdir env cat touch ls grep sh head - Commands available in test + Commands available in test .. conf:: path_variable :type: LIST :default: {cache:executables_path} - ``$PATH`` environment variable passed to the shell + ``$PATH`` environment variable passed to the shell Reference +++++++++ @@ -108,15 +106,15 @@ Reference shell settings are defined under the ``shell:reference`` section: :type: PATH :default: /bin/bash - Path to reference shell (shell which will be compared minishell) - has to support the ``-c`` option (``sh``, ``bash`` and ``zsh`` support it) + Path to reference shell (shell which will be compared minishell) + has to support the ``-c`` option (``sh``, ``bash`` and ``zsh`` support it) .. conf:: args :type: ARGV - Supplementary arguments to the reference shell - (e.g ``--posix`` can be used with bash for a more posix complient behavior) + | Supplementary arguments to the reference shell + | e.g ``--posix`` can be used with bash for a more posix complient behavior Timeout ------- diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst new file mode 100644 index 0000000..e45ff38 --- /dev/null +++ b/docs/gettingstarted.rst @@ -0,0 +1,42 @@ +Getting Started +--------------- + +Installation +++++++++++++ + +.. code-block:: + + $ pip3 install minishell-test + $ pip3 install --user minishell-test # if you don't have root access + +Compatibility ++++++++++++++ + +Your executable **must** support the ``-c`` option which allow to pass command as string. + +.. code-block:: + + $ bash -c 'echo bonjour je suis | cat -e' + bonjour je suis$ + $ ./minishell -c 'echo bonjour je suis | cat -e' + bonjour je suis$ + + +.. note:: + With this setup ``argv[2]`` is what you would usually get in ``line`` from ``get_next_line``. + +Usage ++++++ + +Run all the predefined tests: + +.. code-block:: + + $ cd <MINISHELL> + $ minishell_test + +.. warning:: + If you get ``command not found``, do either of those things: + + * ``~/.local/bin`` to your ``PATH`` environment variable. + * run ``$ python3 -m minishell_test`` instead of ``$ minishell_test`` diff --git a/docs/index.rst b/docs/index.rst index 7726f0a..043c7a2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,73 +1,16 @@ .. program:: minishell_test -minishell_test -============== - -Test for 42 school's minishell project. - -.. .. image:: https://i.imgur.com/98xh2xY.gif - -Getting Started ---------------- - -Installation -++++++++++++ - -.. code-block:: - - $ pip3 install minishell-test - $ pip3 install --user minishell-test # if you don't have root access - -Compatibility -+++++++++++++ - -Your executable **must** support the ``-c`` option which allow to pass command as string. - -.. code-block:: - - $ bash -c 'echo bonjour je suis | cat -e' - bonjour je suis$ - $ ./minishell -c 'echo bonjour je suis | cat -e' - bonjour je suis$ - - -.. note:: - With this setup ``argv[2]`` is what you would usually get in ``line`` from ``get_next_line``. - -Usage -+++++ - -Run all the predefined tests: - -.. code-block:: - - $ cd <MINISHELL> - $ minishell_test - -.. warning:: - If you get ``command not found``, do either of those things: - - * ``~/.local/bin`` to your ``PATH`` environment variable. - * run ``$ python3 -m minishell_test`` instead of ``$ minishell_test`` - - -Documentation -------------- +minishell_test documentation +============================ .. toctree:: - :maxdepth: 2 + :maxdepth: 1 config options developers - -.. code-block:: - - $ minishell_test --help - -The options are explained in more details in :ref:`options <options>`. - +.. include:: gettingstarted.rst Environement variables ---------------------- @@ -94,3 +37,40 @@ Linux ----- It will try to convert to output/status code of ``bash`` on Linux to the one on Mac. + +.. Add individual test +.. ------------------- +.. +.. In your suite function you can use the `test` function. With the following arguments: +.. +.. 1. Command to be tested (output and status will be compared to bash) +.. 2. A command to setup the sandbox directory where the tested command will be run +.. 3. List of files to watch (the content of each file will be compared) +.. +.. ```python +.. test("echo bonjour je suis") # simple command +.. test("cat < somefile", setup="echo file content > somefile") # setup +.. test("ls > somefile", setup="", files=["somefile"]) # watch a file +.. test("echo $A", exports={"A": "a"}) # export variables +.. # in the environment +.. test("echo bonjour", hook=lambda s: s.replace("o", "a")) # pass the shell output +.. # through a hook function +.. +.. test("cat < somefile > otherfile", +.. setup="echo file content > somefile", +.. files=["otherfile"]) +.. ``` +.. +.. ### Add Suite +.. +.. A test suite is a group of related tests. +.. +.. ```python +.. @suite() # @suite(bonus=True) if it's a bonus suite +.. def suite_yoursuitename(test): +.. """ a description of the suite """ +.. test(...) +.. test(...) +.. test(...) +.. ``` +.. |