prefpicker 2.17.0__py3-none-any.whl

prefpicker/templates/schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "prefpicker template schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "pref": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^.+$": {
+          "additionalProperties": false,
+          "type": "object",
+          "properties": {
+            "variants": {
+              "type": "object",
+              "additionalProperties": false,
+              "patternProperties": {
+                "^.+$": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": ["boolean", "integer", "null", "string"]
+                  }
+                }
+              },
+              "required": [
+                "default"
+              ]
+            },
+            "review_on_close": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "integer"
+              }
+            }
+          },
+          "required": [
+            "variants"
+          ]
+        }
+      }
+    },
+    "variant": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "pref",
+    "variant"
+  ]
+}

prefpicker/test_main.py

@@ -0,0 +1,95 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+"""main.py tests"""
+
+from pytest import raises
+
+from .main import main
+from .prefpicker import PrefPicker
+
+
+def test_main_01(tmp_path):
+    """test main()"""
+    prefs_js = tmp_path / "prefs.js"
+    yml = tmp_path / "test.yml"
+    yml.write_text(
+        """
+        variant: []
+        pref:
+          test.a:
+            variants:
+              default: [1]"""
+    )
+    assert main([str(yml), str(prefs_js), "--variant", "default"]) == 0
+    assert prefs_js.is_file()
+
+
+def test_main_02(capsys):
+    """test main() with missing input"""
+    with raises(SystemExit):
+        main(["missing.yml", "prefs.js"])
+    assert "Cannot find input file 'missing.yml'" in capsys.readouterr()[1]
+
+
+def test_main_03(tmp_path):
+    """test main() with built-in input"""
+    prefs_js = tmp_path / "prefs.js"
+    templates = tuple(x.name for x in PrefPicker.templates())
+    assert templates
+    assert main([templates[0], str(prefs_js)]) == 0
+    assert prefs_js.is_file()
+
+
+def test_main_04(tmp_path):
+    """test main() with invalid variant"""
+    prefs_js = tmp_path / "prefs.js"
+    yml = tmp_path / "test.yml"
+    yml.write_text(
+        """
+        variant: []
+        pref:
+          test.a:
+            variants:
+              default: [1]"""
+    )
+    assert main([str(yml), str(prefs_js), "--variant", "x"]) == 1
+    assert not prefs_js.is_file()
+
+
+def test_main_05(tmp_path):
+    """test main() with check results"""
+    prefs_js = tmp_path / "prefs.js"
+    yml = tmp_path / "test.yml"
+    yml.write_text(
+        """
+        variant: [extra]
+        pref:
+          test.a:
+            variants:
+              default: [1, 1]
+              extra: [1, 1]"""
+    )
+    assert main([str(yml), str(prefs_js), "--check", "--variant", "extra"]) == 0
+    assert prefs_js.is_file()
+
+
+def test_main_06(capsys, tmp_path):
+    """test main() with invalid output path"""
+    yml = tmp_path / "test.yml"
+    yml.touch()
+    # output is a directory
+    with raises(SystemExit):
+        main([str(yml), str(tmp_path)])
+    assert "is a directory." in capsys.readouterr()[1]
+    # output to missing directory
+    with raises(SystemExit):
+        main([str(yml), str(tmp_path / "missing" / "prefs.js")])
+    assert "directory does not exist." in capsys.readouterr()[1]
+
+
+def test_main_07(tmp_path):
+    """test main() with invalid input"""
+    yml = tmp_path / "test.yml"
+    yml.write_text("{test{")
+    assert main([str(yml), str(tmp_path / "prefs.js")]) == 1

prefpicker/test_prefpicker.py

@@ -0,0 +1,281 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+"""prefpicker.py tests"""
+
+from pytest import mark, raises
+
+from .prefpicker import PrefPicker, SourceDataError
+
+
+def test_prefpicker_01(tmp_path):
+    """test simple PrefPicker"""
+    yml = tmp_path / "test.yml"
+    yml.write_text(
+        """
+        variant: []
+        pref:
+          test.a:
+            variants:
+              default: [1]"""
+    )
+    picker = PrefPicker.load_template(yml)
+    assert len(picker.variants) == 1
+    assert "default" in picker.variants
+    assert len(picker.prefs) == 1
+    assert "test.a" in picker.prefs
+
+
+@mark.parametrize(
+    "data, msg",
+    [
+        # invalid template
+        ([], "invalid template"),
+        # variant list missing
+        ({"pref": {"a.b": {"variants": {"default": [1]}}}}, "variant list is missing"),
+        # variant definition is invalid type
+        ({"variant": [{"bad": 1}]}, "variant definition must be a string"),
+        # variant is invalid type
+        ({"variant": ""}, "variant is not a list"),
+        # pref dict missing
+        ({"variant": []}, "pref group is missing"),
+        # pref is invalid type
+        ({"pref": [], "variant": []}, "pref is not a dict"),
+        # pref entry is invalid
+        (
+            {"pref": {"a.b": None}, "variant": []},
+            r"'a\.b' entry must contain a dict",
+        ),
+        # pref variants is invalid
+        (
+            {"pref": {"a.b": {"variants": None}}, "variant": []},
+            r"'a\.b' is missing 'variants' dict",
+        ),
+        # pref missing default variant
+        (
+            {"variant": [], "pref": {"test.a": {"variants": {}}}},
+            r"'test\.a' is missing 'default' variant",
+        ),
+        # template with undefined variant
+        (
+            {"variant": [], "pref": {"a.b": {"variants": {"default": [1], "x": [2]}}}},
+            r"'x' in 'a\.b' is not a defined variant",
+        ),
+        # template with unused variant
+        (
+            {"variant": ["unused"], "pref": {"a.b": {"variants": {"default": [1]}}}},
+            "Unused variants 'unused'",
+        ),
+        # pref with empty variant list
+        (
+            {"variant": [], "pref": {"a.b": {"variants": {"default": []}}}},
+            r"'default' in 'a\.b' is empty",
+        ),
+        # pref with invalid variant type
+        (
+            {"variant": [], "pref": {"a.b": {"variants": {"default": "x"}}}},
+            r"variant 'default' in 'a\.b' is not a list",
+        ),
+        # pref variant with invalid type
+        (
+            {"variant": [], "pref": {"a.b": {"variants": {"default": [1.11]}}}},
+            r"unsupported datatype 'float' \(a\.b\)",
+        ),
+    ],
+)
+def test_prefpicker_02(data, msg):
+    """test PrefPicker.verify_data()"""
+    with raises(SourceDataError, match=msg):
+        PrefPicker.verify_data(data)
+
+
+def test_prefpicker_03():
+    """test PrefPicker.check_overwrites()"""
+    raw_data = {
+        "variant": ["fail", "safe"],
+        "pref": {
+            "test.a": {"variants": {"default": [1], "fail": [1, 2], "safe": [3]}},
+            "test.b": {"variants": {"default": [9], "safe": [None]}},
+        },
+    }
+    # use verify_data just to sanity check test data
+    PrefPicker.verify_data(raw_data)
+    ppick = PrefPicker()
+    ppick.variants = set(raw_data["variant"] + ["default"])
+    ppick.prefs = raw_data["pref"]
+    results = tuple(ppick.check_overwrites())
+    assert results
+    assert results[0][0] == "test.a"
+    assert results[0][1] == "fail"
+    assert results[0][2] == 1
+
+
+def test_prefpicker_04():
+    """test PrefPicker.check_duplicates()"""
+    raw_data = {
+        "variant": ["fail", "safe"],
+        "pref": {
+            "test.a": {"variants": {"default": [1], "fail": [1, 2, 3, 1], "safe": [3]}},
+            "test.b": {"variants": {"default": [9], "safe": [None]}},
+        },
+    }
+    # use verify_data just to sanity check test data
+    PrefPicker.verify_data(raw_data)
+    ppick = PrefPicker()
+    ppick.variants = set(raw_data["variant"] + ["default"])
+    ppick.prefs = raw_data["pref"]
+    results = tuple(ppick.check_duplicates())
+    assert results
+    assert results[0][0] == "test.a"
+    assert results[0][1] == "fail"
+
+
+def test_prefpicker_05():
+    """test PrefPicker.check_combinations()"""
+    raw_data = {
+        "variant": ["v1", "v2"],
+        "pref": {
+            "test.a": {"variants": {"default": [1], "v1": [1, 2, 3, 4], "v2": [3]}},
+            "test.b": {"variants": {"default": [2], "v1": [1, 2], "v2": [3]}},
+            "test.c": {"variants": {"default": [1, 3], "v2": [None]}},
+        },
+    }
+    # use verify_data just to sanity check test data
+    PrefPicker.verify_data(raw_data)
+    ppick = PrefPicker()
+    ppick.variants = set(raw_data["variant"] + ["default"])
+    ppick.prefs = raw_data["pref"]
+    results = tuple(ppick.check_combinations())
+    assert len(results) == 2
+    assert results[0][0] == "default"
+    assert results[0][1] == 2
+    assert results[1][0] == "v1"
+    assert results[1][1] == 16
+
+
+def test_prefpicker_06(tmp_path):
+    """test simple PrefPicker.create_prefsjs()"""
+    ppick = PrefPicker()
+    prefs = tmp_path / "prefs.js"
+    ppick.create_prefsjs(prefs)
+    assert prefs.is_file()
+    # check only comments were written to the document
+    with prefs.open("r") as in_fp:
+        for line in in_fp:
+            assert line.startswith("//")
+        assert in_fp.tell() > 0
+
+
+def test_prefpicker_07(tmp_path):
+    """test PrefPicker.create_prefsjs() with variants"""
+    raw_data = {
+        "variant": ["test", "skip"],
+        "pref": {
+            "test.a": {"variants": {"default": [0], "test": [1], "skip": [2]}},
+            "test.b": {"variants": {"default": [True]}},
+        },
+    }
+    PrefPicker.verify_data(raw_data)
+    ppick = PrefPicker()
+    ppick.variants = set(raw_data["variant"] + ["default"])
+    ppick.prefs = raw_data["pref"]
+    prefs = tmp_path / "prefs.js"
+    # test with 'default' variant
+    ppick.create_prefsjs(prefs)
+    assert prefs.is_file()
+    prefs_data = prefs.read_text()
+    assert "defined by variant 'default'" not in prefs_data
+    assert 'user_pref("test.a", 0);\n' in prefs_data
+    assert 'user_pref("test.b", true);\n' in prefs_data
+    # test with 'test' variant
+    ppick.create_prefsjs(prefs, variant="test")
+    assert prefs.is_file()
+    prefs_data = prefs.read_text()
+    assert 'user_pref("test.a", 1);\n' in prefs_data
+    assert 'user_pref("test.b", true);\n' in prefs_data
+    assert "// 'test.a' defined by variant 'test'" in prefs_data
+
+
+def test_prefpicker_08(tmp_path):
+    """test PrefPicker.create_prefsjs() with different values"""
+    raw_data = {
+        "variant": [],
+        "pref": {
+            # type int
+            "test.a": {
+                "variants": {
+                    "default": [0, 1],
+                }
+            },
+            # type None (skip)
+            "test.b": {
+                "variants": {
+                    "default": [None],
+                }
+            },
+            # type string
+            "test.c": {
+                "variants": {
+                    "default": ["test string"],
+                }
+            },
+            # type string (with quotes)
+            "test.d": {
+                "variants": {
+                    "default": ["'test' \"string\""],
+                }
+            },
+            # type bool
+            "test.e": {
+                "variants": {
+                    "default": [True, False],
+                }
+            },
+            # add None twice to trigger the 'skip' code path and write out comment
+            "test.f": {
+                "variants": {
+                    "default": [None, None],
+                }
+            },
+            # mixed types
+            "test.g": {
+                "variants": {
+                    "default": ["foo", True, 0],
+                }
+            },
+        },
+    }
+    PrefPicker.verify_data(raw_data)
+    ppick = PrefPicker()
+    ppick.variants = set(raw_data["variant"] + ["default"])
+    ppick.prefs = raw_data["pref"]
+    prefs = tmp_path / "prefs.js"
+    ppick.create_prefsjs(prefs)
+    assert prefs.is_file()
+    prefs_data = prefs.read_text()
+    assert 'user_pref("test.b",' not in prefs_data
+    assert "user_pref(\"test.c\", 'test string');" in prefs_data
+    # test with unsupported value datatype
+    raw_data = {"variant": [], "pref": {"boom.": {"variants": {"default": [1.01]}}}}
+    ppick.variants = set(raw_data["variant"] + ["default"])
+    ppick.prefs = raw_data["pref"]
+    with raises(SourceDataError, match="Unsupported datatype"):
+        ppick.create_prefsjs(prefs)
+
+
+def test_prefpicker_09(tmp_path):
+    """test PrefPicker.load_template() with invalid YAML"""
+    yml = tmp_path / "test.yml"
+    yml.write_text("{-{-{-{-:::")
+    with raises(SourceDataError, match=r"invalid YAML"):
+        PrefPicker.load_template(yml)
+
+
+def test_prefpicker_10():
+    """test PrefPicker.lookup_template()"""
+    # unknown template
+    assert PrefPicker.lookup_template("missing") is None
+    # existing template
+    template = next(PrefPicker.templates(), None)
+    assert template is not None
+    assert PrefPicker.lookup_template(template.name)

prefpicker/test_templates.py

@@ -0,0 +1,44 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+"""template.py tests"""
+
+from difflib import unified_diff
+
+from yaml import safe_dump, safe_load
+
+from .main import main
+from .prefpicker import PrefPicker
+
+
+def test_templates_01(tmp_path):
+    """sanity check template YAML files"""
+    prefs_js = tmp_path / "prefs.js"
+    checked = []
+    for template in PrefPicker.templates():
+        assert main([str(template), str(prefs_js), "--check"]) == 0
+        assert prefs_js.is_file()
+        prefs_js.unlink()
+        checked.append(template.name)
+    assert "browser-fuzzing.yml" in checked
+
+
+def test_templates_02():
+    """check formatting of template YAML files"""
+    for template in PrefPicker.templates():
+        with template.open() as in_fp:
+            # remove comments
+            input_yml = "".join(x for x in in_fp if not x.lstrip().startswith("#"))
+        formatted_yml = safe_dump(safe_load(input_yml), indent=2, width=100)
+        diff = tuple(
+            unified_diff(
+                input_yml.splitlines(),
+                formatted_yml.splitlines(),
+                fromfile=str(template),
+                tofile="formatting fixes",
+                lineterm="",
+            )
+        )
+        if diff:
+            formatted = "\n".join(diff)
+            raise AssertionError(f"Formatting changes required:\n{formatted}")

prefpicker-2.17.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: prefpicker
+Version: 2.17.0
+Summary: PrefPicker - Manage & generate prefs.js files
+Home-page: https://github.com/MozillaSecurity/prefpicker
+Author: Tyson Smith
+Author-email: twsmith@mozilla.com
+Maintainer: Mozilla Fuzzing Team
+Maintainer-email: fuzzing@mozilla.com
+License: MPL 2.0
+Keywords: firefox fuzz fuzzing test testing
+Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Dynamic: license-file
+
+PrefPicker
+==========
+[![CI](https://github.com/MozillaSecurity/prefpicker/actions/workflows/ci.yml/badge.svg)](https://github.com/MozillaSecurity/prefpicker/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/MozillaSecurity/prefpicker/branch/master/graph/badge.svg)](https://codecov.io/gh/MozillaSecurity/prefpicker)
+[![Matrix](https://img.shields.io/badge/chat-%23fuzzing-green?logo=matrix)](https://matrix.to/#/#fuzzing:mozilla.org)
+[![PyPI](https://img.shields.io/pypi/v/prefpicker)](https://pypi.org/project/prefpicker)
+
+
+Manage & generate prefs.js files for use when testing Firefox. This tool is intended to simplify the use and tracking of prefs used by
+our fuzzing tools. The template files can be modified to allow the creation of custom prefs.js files without
+the need to maintain a separate mostly duplicate version of a prefs file.
+
+YAML Template Structure
+-----------------------
+
+The template document is made up of variants, prefs and values.
+
+_**pref**_ is the name of the preference that will be added to the prefs.js file. This is an unquoted string.
+Valid prefs can be found in [all.js](https://hg.mozilla.org/mozilla-central/file/tip/modules/libpref/init/all.js) or in [StaticPrefList.yml](https://hg.mozilla.org/mozilla-central/file/tip/modules/libpref/init/StaticPrefList.yaml).
+
+__**review_on_close**__ is optional. It is a list of relevant Bugzilla IDs used to help avoid obsolete entries. When all bugs in the list are closed the entry will be reviewed and removed if appropriate.
+
+_**value**_ can be a `bool`, `int`, `string` or `null`. Adding multiple potential values is possible.
+When multiple values are present one is chosen at random when generating the output.
+Using a value of `null` will exclude the pref from the prefs.js file (acts as browser default).
+
+_**variant**_ is a subset of values to be used in place of the default values.
+The default variant is used unless a variant is specified.
+
+There are a few mechanisms in place to help keep the file in order:
+- All prefs must have a default variant
+- All variants must be defined in the variant list
+- All variants in the variant list must be used
+- All variants must be a list and contain values
+
+```yml
+# example.yml
+variant:              # list of extra variants, default is implied
+- alt                 # name of variant
+pref:
+  pref.name:          # unquoted name of the pref used in prefs.js
+    review_on_close:  # optional
+    - 123456
+    variants:
+      default:        # variant definition, default is required
+      - 0             # potential value
+      alt:            # extra optional variant
+      - 1             # if multiple values are defined one is chosen randomly
+      - null          # null is a special case meaning exclude the pref
+```
+
+Updating Templates and Adding Prefs
+-----------------------------------
+Prefs are found in the `.yml` files in the [template](/src/prefpicker/templates) directory.
+Only prefs that are ready to be tested should be added.
+When adding a pref to a template it is encouraged to add a comment that provides justification and points to a bug in Bugzilla for additional context.
+If a pref does not already exist and is only used with non-default variants a `null` entry must be added to the default variant.
+
+Quick Setup
+-----------
+
+Use pip to install prefpicker.
+
+```bash
+pip install prefpicker
+```
+
+Examples
+--------
+
+Use a built-in [template](/src/prefpicker/templates) to generate an up-to-date `prefs.js` file.
+
+```bash
+prefpicker browser-fuzzing.yml prefs.js
+```
+
+Or generate a `prefs.js` file from a custom template using the `webrender` variant:
+
+```bash
+user@machine:~/prefpicker$ prefpicker custom/template.yml ~/Desktop/prefs.js --variant webrender
+Loading 'template.yml'...
+Loaded 255 prefs and 5 variants
+Generating 'prefs.js' using variant 'webrender'...
+Done.
+```
+
+The resulting `prefs.js` file is ready to be used with Firefox. It will look something like this:
+
+```js
+// Generated with PrefPicker @ 2020-02-08 00:50:29 UTC
+// Variant 'webrender'
+/// ... snip
+user_pref("fuzzing.enabled", true);
+/// ... snip
+// 'gfx.webrender.all' defined by variant 'webrender'
+user_pref("gfx.webrender.all", true);
+/// ... snip
+```

prefpicker-2.17.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+prefpicker/__init__.py,sha256=XWsqb0fPEcXI12OFAGU0ftCAiUAnNTyyAzADC62x1-g,348
+prefpicker/__main__.py,sha256=8-D6LzRgVF2PwY7XXs1Fs-Nzy0NPOl04DKMmk18SqsU,282
+prefpicker/main.py,sha256=V10iJ6UiNc5aACflJSHjJl59kc6f1uJhuSfRFkrsJqw,3842
+prefpicker/prefpicker.py,sha256=tKnwVdO0bwmOv1XjNntojAiCPwHsAGNx3X6SMxLpaJQ,9817
+prefpicker/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+prefpicker/test_main.py,sha256=6K4eKDvXwy7ogdj-tOKIfjCJjr0CnQwfFyobjpj4hgk,2644
+prefpicker/test_prefpicker.py,sha256=ojoYid7rC57dpWqjpnXnp7_E1F84OBa6iBKrAwl1CyU,9330
+prefpicker/test_templates.py,sha256=jlu3QTWzn1iE_7ljQs3byBAvUaGjeFZPNuBySSvSUoM,1496
+prefpicker/templates/browser-fuzzing.yml,sha256=wAuOaGPHoLQY6TnuvE0b67YOvRBWMVfMj6C-Hd64BXs,23756
+prefpicker/templates/schema.json,sha256=D14picYNGMXV0WObBxeZFb7l_U_OJkZIi29Rv25M2nA,1293
+prefpicker-2.17.0.dist-info/licenses/LICENSE,sha256=HyVuytGSiAUQ6ErWBHTqt1iSGHhLmlC8fO7jTCuR8dU,16725
+prefpicker-2.17.0.dist-info/METADATA,sha256=LHgAJLnJzhqWKYK9bc7IVzQijRarWvx8ExS7VfMab54,4949
+prefpicker-2.17.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+prefpicker-2.17.0.dist-info/entry_points.txt,sha256=og57vebqGVtgg_OZGO39WUb13H8wMzcnNBh4h-t26K0,52
+prefpicker-2.17.0.dist-info/top_level.txt,sha256=H-QqR-VZXNwG4ya7wnqx5NA-yua6D9uQuBquP2zCRbc,11
+prefpicker-2.17.0.dist-info/RECORD,,

prefpicker-2.17.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

prefpicker-2.17.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+prefpicker = prefpicker.main:main