{"id":22306186,"url":"https://github.com/renatahodovan/grammarinator","last_synced_at":"2025-04-13T00:49:32.816Z","repository":{"id":38421575,"uuid":"91344700","full_name":"renatahodovan/grammarinator","owner":"renatahodovan","description":"ANTLR v4 grammar-based test generator","archived":false,"fork":false,"pushed_at":"2025-02-28T09:02:03.000Z","size":773,"stargazers_count":363,"open_issues_count":10,"forks_count":62,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-13T00:49:28.734Z","etag":null,"topics":["antlr4","bughunting","fuzzer","fuzzing","grammar-based-testing","hacktoberfest","random-testing","security","test-automation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/renatahodovan.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.rst","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-15T14:02:45.000Z","updated_at":"2025-04-12T01:47:25.000Z","dependencies_parsed_at":"2024-05-19T14:43:08.052Z","dependency_job_id":"08a15659-2d3b-46b8-8aea-dbafa2a1f310","html_url":"https://github.com/renatahodovan/grammarinator","commit_stats":{"total_commits":216,"total_committers":7,"mean_commits":"30.857142857142858","dds":0.3842592592592593,"last_synced_commit":"a4fff1d57654c8a3177b92a2ac99a719c1302d2e"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renatahodovan%2Fgrammarinator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renatahodovan%2Fgrammarinator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renatahodovan%2Fgrammarinator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/renatahodovan%2Fgrammarinator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/renatahodovan","download_url":"https://codeload.github.com/renatahodovan/grammarinator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650436,"owners_count":21139672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antlr4","bughunting","fuzzer","fuzzing","grammar-based-testing","hacktoberfest","random-testing","security","test-automation"],"created_at":"2024-12-03T19:14:53.509Z","updated_at":"2025-04-13T00:49:32.798Z","avatar_url":"https://github.com/renatahodovan.png","language":"Python","funding_links":[],"categories":["Tools"],"sub_categories":["File Format Fuzzers"],"readme":"=============\nGrammarinator\n=============\n*ANTLRv4 grammar-based test generator*\n\n.. image:: https://img.shields.io/pypi/v/grammarinator?logo=python\u0026logoColor=white\n   :target: https://pypi.org/project/grammarinator/\n.. image:: https://img.shields.io/pypi/l/grammarinator?logo=open-source-initiative\u0026logoColor=white\n   :target: https://pypi.org/project/grammarinator/\n.. image:: https://img.shields.io/github/actions/workflow/status/renatahodovan/grammarinator/main.yml?branch=master\u0026logo=github\u0026logoColor=white\n   :target: https://github.com/renatahodovan/grammarinator/actions\n.. image:: https://img.shields.io/coveralls/github/renatahodovan/grammarinator/master?logo=coveralls\u0026logoColor=white\n   :target: https://coveralls.io/github/renatahodovan/grammarinator\n.. image:: https://img.shields.io/readthedocs/grammarinator?logo=read-the-docs\u0026logoColor=white\n   :target: http://grammarinator.readthedocs.io/en/latest/\n\n.. start included documentation\n\n*Grammarinator* is a random test generator / fuzzer that creates test cases\naccording to an input ANTLR_ v4 grammar. The motivation behind this\ngrammar-based approach is to leverage the large variety of publicly\navailable `ANTLR v4 grammars`_.\n\nThe `trophy page`_ of the found issues is available from the wiki.\n\n.. _ANTLR: http://www.antlr.org\n.. _`ANTLR v4 grammars`: https://github.com/antlr/grammars-v4\n.. _`trophy page`: https://github.com/renatahodovan/grammarinator/wiki\n\n\nRequirements\n============\n\n* Python_ \u003e= 3.8\n* Java_ SE \u003e= 11 JRE or JDK (the latter is optional)\n\n.. _Python: https://www.python.org\n.. _Java: https://www.oracle.com/java/\n\n\nInstall\n=======\n\nTo use *Grammarinator* in another project, it can be added to ``setup.cfg`` as\nan install requirement (if using setuptools_ with declarative config):\n\n.. code-block:: ini\n\n    [options]\n    install_requires =\n        grammarinator\n\nTo install *Grammarinator* manually, e.g., into a virtual environment, use\npip_::\n\n    pip install grammarinator\n\nThe above approaches install the latest release of *Grammarinator* from PyPI_.\nAlternatively, for the development version, clone the project and perform a\nlocal install::\n\n    pip install .\n\n.. _setuptools: https://github.com/pypa/setuptools\n.. _pip: https://pip.pypa.io\n.. _PyPI: https://pypi.org/\n\n\nUsage\n=====\n\nAs a first step, *Grammarinator* takes an `ANTLR v4 grammar`_ and creates a test\ngenerator script in Python3. Grammarinator supports a subset of the features\nof the ANTLR grammar which is introduced in the Grammar overview section of the\ndocumentation. The produced generator can be subclassed later to customize it\nfurther if needed.\n\nBasic command-line syntax of test generator creation::\n\n    grammarinator-process \u003cgrammar-file(s)\u003e -o \u003coutput-directory\u003e --no-actions\n\n..\n\n    **Notes**\n\n    *Grammarinator* uses the `ANTLR v4 grammar`_ format as its input, which\n    makes existing grammars (lexer and parser rules) easily reusable. However,\n    because of the inherently different goals of a fuzzer and a parser, inlined\n    code (actions and conditions, header and members blocks) are most probably\n    not reusable, or even preventing proper execution. For first experiments\n    with existing grammar files, ``grammarinator-process`` supports the\n    command-line option ``--no-actions``, which skips all such code blocks\n    during fuzzer generation. Once inlined code is tuned for fuzzing, that\n    option may be omitted.\n\n.. _`ANTLR v4 grammar`: https://github.com/antlr/grammars-v4\n\nAfter having generated and optionally customized a fuzzer, it can be executed\nby the ``grammarinator-generate`` script (or by manually instantiating it in a\ncustom-written driver, of course).\n\nBasic command-line syntax of ``grammarinator-generate``::\n\n    grammarinator-generate \u003cgenerator\u003e -r \u003cstart-rule\u003e -d \u003cmax-depth\u003e \\\n      -o \u003coutput-pattern\u003e -n \u003cnumber-of-tests\u003e \\\n      -t \u003ctransformer1\u003e -t \u003ctransformer2\u003e\n\nBeside generating test cases from scratch based on the ANTLR grammar,\nGrammarinator is also able to recombine existing inputs or mutate only a small\nportion of them. To use these additional generation approaches, a population of\nselected test cases has to be prepared. The preparation happens with the\n``grammarinator-parse`` tool, which processes the input files with an ANTLR\ngrammar (possibly with the same one as the generator grammar) and builds\ngrammarinator tree representations from them (with .grt extension). Having a\npopulation of such .grt files, ``grammarinator-generate`` can make use of them\nwith the ``--population`` cli option. If the ``--population`` option is set,\nthen Grammarinator will choose a strategy (generation, mutation, or\nrecombination) randomly at the creation of every new test case. If any of the\nstrategies is unwanted, they can be disabled with the ``--no-generate``,\n``--no-mutate`` or ``--no-recombine`` options.\n\nBasic command line syntax of ``grammarinator-parse``::\n\n  grammarinator-parse \u003cgrammar-file(s)\u003e -r \u003cstart-rule\u003e \\\n    -i \u003cinput_file(s)\u003e -o \u003coutput-directory\u003e\n\n..\n\n    **Notes**\n\n    Real-life grammars often use recursive rules to express certain patterns.\n    However, when using such rule(s) for generation, we can easily end up in an\n    unexpectedly deep call stack. With the ``--max-depth`` or ``-d`` options,\n    this depth - and also the size of the generated test cases - can be\n    controlled.\n\n    Another specialty of the ANTLR grammars is that they support so-called\n    hidden tokens. These rules typically describe such elements of the target\n    language that can be placed basically anywhere without breaking the syntax.\n    The most common examples are comments or whitespaces. However, when using\n    these grammars - which don't define explicitly where whitespace may or may\n    not appear in rules - to generate test cases, we have to insert the missing\n    spaces manually. This can be done by applying a serializer (with the ``-s``\n    option) to the tree representation of the output tests. A simple serializer\n    - that inserts a space after every unparser rule - is provided by\n    *Grammarinator* (``grammarinator.runtime.simple_space_serializer``).\n\n    In some cases, we may want to postprocess the output tree itself (without\n    serializing it). For example, to enforce some logic that cannot be expressed\n    by a context-free grammar. For this purpose the transformer mechanism can be\n    used (with the ``-t`` option). Similarly to the serializers, it will take a\n    tree as input, but instead of creating a string representation, it is\n    expected to return the modified (transformed) tree object.\n\n    As a final thought, one must not forget that the original purpose of\n    grammars is the syntax-wise validation of various inputs. As a consequence,\n    these grammars encode syntactic expectations only and not semantic rules. If\n    we still want to add semantic knowledge into the generated test, then we can\n    inherit custom fuzzers from the generated ones and redefine methods\n    corresponding to lexer or parser rules in ways that encode the required\n    knowledge (e.g.: HTMLCustomGenerator_).\n\n.. _HTMLCustomGenerator: examples/fuzzer/HTMLCustomGenerator.py\n\n\nWorking Example\n===============\n\nThe repository contains a minimal example_ to generate HTML files. To give it\na try, run the processor first::\n\n    grammarinator-process examples/grammars/HTMLLexer.g4 examples/grammars/HTMLParser.g4 \\\n      -o examples/fuzzer/\n\n\nThen, use the generator to produce test cases::\n\n    grammarinator-generate HTMLCustomGenerator.HTMLCustomGenerator -r htmlDocument -d 20 \\\n      -o examples/tests/test_%d.html -n 100 \\\n      -s HTMLGenerator.html_space_serializer \\\n      --sys-path examples/fuzzer/\n\n.. _example: examples/\n\n\nCompatibility\n=============\n\n*Grammarinator* was tested on:\n\n* Linux (Ubuntu 16.04 / 18.04 / 20.04)\n* OS X / macOS (10.12 / 10.13 / 10.14 / 10.15 / 11)\n* Windows (Server 2012 R2 / Server version 1809 / Windows 10)\n\n\nCitations\n=========\n\nBackground on *Grammarinator* is published in:\n\n* Renata Hodovan, Akos Kiss, and Tibor Gyimothy. Grammarinator: A Grammar-Based\n  Open Source Fuzzer.\n  In Proceedings of the 9th ACM SIGSOFT International Workshop on Automating\n  Test Case Design, Selection, and Evaluation (A-TEST 2018), pages 45-48, Lake\n  Buena Vista, Florida, USA, November 2018. ACM.\n  https://doi.org/10.1145/3278186.3278193\n\n.. end included documentation\n\nCopyright and Licensing\n=======================\n\nLicensed under the BSD 3-Clause License_.\n\n.. _License: LICENSE.rst\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenatahodovan%2Fgrammarinator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frenatahodovan%2Fgrammarinator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frenatahodovan%2Fgrammarinator/lists"}