diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.rst | 2 | ||||
| -rw-r--r-- | docs/bonus.rst | 6 | ||||
| -rw-r--r-- | docs/conf.py | 6 | ||||
| -rw-r--r-- | docs/config.rst | 139 | ||||
| -rw-r--r-- | docs/config.rst.bak | 142 | ||||
| -rw-r--r-- | docs/custom_test.rst | 41 | ||||
| -rw-r--r-- | docs/disclaimer.rst | 13 | ||||
| -rw-r--r-- | docs/index.rst | 73 | ||||
| -rw-r--r-- | docs/linux.rst | 6 | ||||
| -rw-r--r-- | docs/memory_leaks.rst | 5 |
10 files changed, 293 insertions, 140 deletions
diff --git a/docs/README.rst b/docs/README.rst index f8a56e8..86c571a 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -23,4 +23,4 @@ Test for 42 school's minishell project. Documentation ------------- -The full documentation for this project is available at `minishell-test.readthedocs.io<https://minishell-test.readthedocs.io>`_. +The full documentation for this project is available at `minishell-test.readthedocs.io <https://minishell-test.readthedocs.io>`_. diff --git a/docs/bonus.rst b/docs/bonus.rst new file mode 100644 index 0000000..df4685e --- /dev/null +++ b/docs/bonus.rst @@ -0,0 +1,6 @@ +Bonus +===== + + +See :ref:`config bonus` +See :ref:`options bonus` diff --git a/docs/conf.py b/docs/conf.py index b353a1c..339bb98 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -70,12 +70,6 @@ def setup(app): names=('type',), bodyrolename='class' ), - Field( - 'default', - label='Default', - has_arg=False, - names=('default',), - ), ] ) diff --git a/docs/config.rst b/docs/config.rst index 884cf9b..f35251d 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -3,139 +3,140 @@ Configuration ============= -Configuration file ------------------- +File +---- -It looks for a ``minishell_test.cfg`` file in your project directory. +The configuration file is named ``minishell_test.cfg`` and should be located at the root of your project. Here is what the default configuration looks like: .. include:: ../minishell_test/data/default.cfg - :code: cfg + :code: ini -The format of this file is described in more details `here <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 ------ -Global settings are defined under the ``minishell_test`` section: - -.. code-block:: cfg - - [minishell_test] - bonus = true +Global settings are defined under the ``[minishell_test]`` section. .. conf:: bonus :type: true|false - :default: false - Run the bonus tests + Enable the bonus tests (:ref:`bonus`). -.. conf:: exec_name +.. conf:: make - :type: PATH - :default: minishell + :type: true|false - Minishell executable name + Run the ``make`` command in your project directory before the test. -.. conf:: make +.. conf:: make_args - :type: true|false - :default: true + :type: space separated list - Run ``make`` in your project directory before the test + | Argument given to the ``make`` command. + | The default value (``MINISHELL_TEST_FLAGS=-DMINISHELL_TEST``) allows you to do conditional compilation + to support both the ``-c`` option and the :ref:`subject` + (which doesn't say anything about options, so we assumed the minishell executable didn't take any). -.. conf:: pager + | In your ``Makefile`` add ``$(MINISHELL_TEST_FLAGS)`` in your object compilation command. + (e.g ``$(CC) $(CCFLAGS) -c -o $@ $<``) - :type: NAME - :default: less + | You can then have something resembling the following in your ``main``: - Pager to use when viewing your results + .. code:: c -.. conf:: log_path + #ifndef MINISHELL_TEST + int main(int argc, char **argv) + { + if (argc != 1) error; + ... + } + #else + int main(int argc, char **argv) + { + if (argc != 3 && strcmp(argv[1], "-c") == 0) do the thing; + ... + } + #endif - :type: PATH - :default: minishell_test.log +.. conf:: check_error_messages - File where to put the test results + :type: true|false -.. conf:: cache_path + | If is ``true``, will ignore the content of the error messages outputted by the reference shell, + | Useful if you have implemented your own error messages and don't want to copy bash's ones. + +.. conf:: pager - :type: PATH - :default: $XDG_CACHE_HOME/minishell_test ^ ~/.cache/minishell_test + :type: command name + | Pager to use when viewing your results after the tests finished running. + | Will be called like so: ``{pager} {log_filename}``. Shell ----- -Shell settings are defined under the ``shell`` section: - -.. code-block:: cfg - - [shell] - available_commands = ls,cat +Shell settings are defined under the ``[shell]`` section. .. conf:: available_commands - :type: LIST - :default: rmdir env cat touch ls grep sh head + :type: multi-line list + + Commands available in a test. - Commands available in test + .. warning:: + Some of the default tests won't serve their purpose + if the default available commands are not present. .. conf:: path_variable - :type: LIST - :default: {cache:executables_path} + :type: string (``:`` separated directories) - ``$PATH`` environment variable passed to the shell + ``$PATH`` environment variable passed to the shell. + + .. note:: + ``{shell_available_commands_dir}`` will be replaced by the directory + where the available commands are stored. Reference +++++++++ -Reference shell settings are defined under the ``shell:reference`` section: - -.. code-block:: cfg - - [shell:reference] - path = /bin/sh +Reference shell settings are defined under the ``[shell:reference]`` section. .. conf:: path - :type: PATH - :default: /bin/bash + :type: path + + Path to reference shell, the one to which minishell will be compared. - Path to reference shell (shell which will be compared minishell) - has to support the ``-c`` option (``sh``, ``bash`` and ``zsh`` support it) + .. note:: + has to support the ``-c`` option, ``sh``, ``bash`` and ``zsh`` support it. .. conf:: args - :type: ARGV + :type: space separated list - | 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 compliant behavior. Timeout ------- -Timeout settings are defined under the ``timeout`` section: - -.. code-block:: cfg - - [timeout] - leaks = 60 +Timeout settings are defined under the ``[timeout]`` section. .. conf:: test - :type: FLOAT - :default: 0.5 + :type: float (seconds) - Time before a timeout occurs on a regular test (in seconds) + Time before a timeout occurs on a regular test. .. conf:: leaks - :type: FLOAT - :default: 10 + :type: float (seconds) - Time before a timeout occurs on a leak test (with valgrind) (in seconds) + Time before a timeout occurs on a leak test (with ``valgrind``). diff --git a/docs/config.rst.bak b/docs/config.rst.bak new file mode 100644 index 0000000..9d2c5bc --- /dev/null +++ b/docs/config.rst.bak @@ -0,0 +1,142 @@ +.. bt in -*- rst -*- mode! + +Configuration +============= + +File +---- + +The configuration file is named ``minishell_test.cfg`` and should be located at the root of your project. + +Here is what the default configuration looks like: + +.. include:: ../minishell_test/data/default.cfg + :code: ini + + +The format of this file is described in more details +`here <https://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_. + +Global +------ + +Global settings are defined under the ``[minishell_test]`` section. + +.. conf:: bonus + + :type: true|false + + Enable the bonus tests (:ref:`bonus`). + +.. conf:: make + + :type: true|false + + Run the ``make`` command in your project directory before the test. + +.. conf:: make_args + + :type: space separated list + + | Argument given to the ``make`` command. + | The default value (``MINISHELL_TEST_FLAGS=-DMINISHELL_TEST``) allows you to do conditional compilation + to support both the ``-c`` option and the :ref:`subject` + (which doesn't say anything about options, so we assumed the minishell executable didn't take any). + + | In your ``Makefile`` add ``$(MINISHELL_TEST_FLAGS)`` in your object compilation command. + (e.g ``$(CC) $(CCFLAGS) -c -o $@ $<``) + + | You can then have something resembling the following in your ``main``: + + .. code:: c + + #ifndef MINISHELL_TEST + int main(int argc, char **argv) + { + if (argc != 1) error; + ... + } + #else + int main(int argc, char **argv) + { + if (argc != 3 && strcmp(argv[1], "-c") == 0) do the thing; + ... + } + #endif + +.. conf:: check_error_messages + + :type: true|false + + | If is ``true``, will ignore the content of the error messages outputed by the reference shell, + | Usefull if you have implemented your own error messages and don't want to copy bash's ones. + +.. conf:: pager + + :type: command name + + | Pager to use when viewing your results after the tests finished running. + | Will be called like so: ``{pager} {log_filename}``. + +Shell +----- + +Shell settings are defined under the ``[shell]`` section. + +.. conf:: available_commands + + :type: multiline list + + Commands available in a test. + + .. warning:: + Some of the default tests won't serve their purpose + if the default available commands are not present. + +.. conf:: path_variable + + :type: string (``:`` separated directories) + + ``$PATH`` environment variable passed to the shell. + + .. note:: + ``{shell_available_commands_dir}`` will be replaced by the directory + where the available commands are stored. + +Reference ++++++++++ + +Reference shell settings are defined under the ``[shell:reference]`` section. + +.. conf:: path + + :type: path + + Path to reference shell, the one to which minishell will be compared. + + .. note:: + has to support the ``-c`` option, ``sh``, ``bash`` and ``zsh`` support it. + +.. conf:: args + + :type: space separated list + + | Supplementary arguments to the reference shell. + | e.g ``--posix`` can be used with bash for a more posix complient behavior. + +Timeout +------- + +Timeout settings are defined under the ``[timeout]`` section. + +.. conf:: test + + :type: float (seconds) + + Time before a timeout occurs on a regular test. + +.. conf:: leaks + + :type: float (seconds) + + Time before a timeout occurs on a leak test (with valgrind). diff --git a/docs/custom_test.rst b/docs/custom_test.rst new file mode 100644 index 0000000..1d5971c --- /dev/null +++ b/docs/custom_test.rst @@ -0,0 +1,41 @@ +Add Custom Tests +================ + +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) + +.. code:: 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"]) + +Suite +----- + +A test suite is a group of related tests. + +.. code:: python + + @suite() # @suite(bonus=True) if it's a bonus suite + def suite_yoursuitename(test): + """ a description of the suite """ + test(...) + test(...) + test(...) diff --git a/docs/disclaimer.rst b/docs/disclaimer.rst new file mode 100644 index 0000000..9e32b28 --- /dev/null +++ b/docs/disclaimer.rst @@ -0,0 +1,13 @@ +Disclaimer +========== + +Environement variables +---------------------- + +This test only gives the ``PATH`` and ``TERM`` environment variables to your minishell by default (see :ref:`config env`). + +You can test this quickly with :option:`--try`. + +.. warning:: + Please check that your project still work with this environment before creating an issue or messaging me on Slack. + diff --git a/docs/index.rst b/docs/index.rst index 043c7a2..ec08d8f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,73 +4,18 @@ minishell_test documentation ============================ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + gettingstarted config options + bonus + memory_leaks + linux + custom_test + disclaimer developers -.. include:: gettingstarted.rst - -Environement variables ----------------------- - -This test only gives the ``PATH`` and ``TERM`` environment variables to your minishell by default (see :ref:`config env`). - -You can test this quickly with :option:`--try`. - -.. warning:: - Please check that your project still work with this environment before creating an issue or messaging me on Slack. - -Bonus ------ +.. include:: disclaimer.rst -See :ref:`config bonus` -See :ref:`options bonus` - -Memory leaks ------------- - -See :ref:`options leaks` - -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(...) -.. ``` -.. +.. include:: gettingstarted.rst diff --git a/docs/linux.rst b/docs/linux.rst new file mode 100644 index 0000000..97cff50 --- /dev/null +++ b/docs/linux.rst @@ -0,0 +1,6 @@ + +Linux +----- + +It will try to convert to output/status code of ``bash`` on Linux to the one on Mac. + diff --git a/docs/memory_leaks.rst b/docs/memory_leaks.rst new file mode 100644 index 0000000..27aca4c --- /dev/null +++ b/docs/memory_leaks.rst @@ -0,0 +1,5 @@ + +Memory leaks +------------ + +See :ref:`options leaks` |