factory-bot 0.0.1__tar.gz

factory_bot-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+# Packages
+*.egg
+*.egg-info
+build
+dist
+eggs
+sdist
+*.pyc
+.coverage
+.pytest_cache
+.venv
+.claude/worktrees
+.ruff_cache

factory_bot-0.0.1/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+## 0.0.1 - 2026-10-18
+
+- Define factories with `@factory(Model)` and build them with `build` / `attributes_for`: static, lazy (dependencies injected by parameter name) and `sequence` attributes, traits, and a shared seedable `fake`. Faker is now a dependency.

factory_bot-0.0.1/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Daniel Pepper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

factory_bot-0.0.1/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: factory_bot
+Version: 0.0.1
+Summary: Test data factories with the ergonomics of Ruby's factory_bot
+Project-URL: Homepage, https://github.com/dpep/py_factory_bot
+Project-URL: Issues, https://github.com/dpep/py_factory_bot/issues
+Project-URL: Changelog, https://github.com/dpep/py_factory_bot/blob/main/CHANGELOG.md
+Author: Daniel Pepper
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: factories,factory_bot,fixtures,testing
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: faker
+Provides-Extra: django
+Requires-Dist: django; extra == 'django'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+factory_bot
+======
+Test data factories with the ergonomics of Ruby's [factory_bot](https://github.com/thoughtbot/factory_bot).
+
+Early development: the API is still settling.
+
+
+### Install
+```pip install factory_bot```
+
+
+### Usage
+```python
+from factory_bot import build, factory, fake, sequence
+
+@factory(User)
+def user(f):
+    f.first_name = fake.first_name                    # callables run per build
+    f.email = lambda first_name: f"{first_name}@example.com".lower()  # dependencies by name
+    f.username = sequence(lambda n: f"user{n}")
+    f.admin = False
+
+    @f.trait
+    def admin(f):
+        f.admin = True
+
+build("user")
+# User(first_name='Dennis', email='dennis@example.com', username='user1', admin=False)
+
+build("user", "admin", first_name="Jane")
+# User(first_name='Jane', email='jane@example.com', username='user2', admin=True)
+```
+
+----
+[![installs](https://img.shields.io/pypi/dm/factory_bot?label=installs)](https://pypi.org/project/factory_bot)

factory_bot-0.0.1/README.md

@@ -0,0 +1,35 @@
+factory_bot
+======
+Test data factories with the ergonomics of Ruby's [factory_bot](https://github.com/thoughtbot/factory_bot).
+
+Early development: the API is still settling.
+
+
+### Install
+```pip install factory_bot```
+
+
+### Usage
+```python
+from factory_bot import build, factory, fake, sequence
+
+@factory(User)
+def user(f):
+    f.first_name = fake.first_name                    # callables run per build
+    f.email = lambda first_name: f"{first_name}@example.com".lower()  # dependencies by name
+    f.username = sequence(lambda n: f"user{n}")
+    f.admin = False
+
+    @f.trait
+    def admin(f):
+        f.admin = True
+
+build("user")
+# User(first_name='Dennis', email='dennis@example.com', username='user1', admin=False)
+
+build("user", "admin", first_name="Jane")
+# User(first_name='Jane', email='jane@example.com', username='user2', admin=True)
+```
+
+----
+[![installs](https://img.shields.io/pypi/dm/factory_bot?label=installs)](https://pypi.org/project/factory_bot)

factory_bot-0.0.1/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling >= 1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "factory_bot"
+dynamic = ["version"]
+description = "Test data factories with the ergonomics of Ruby's factory_bot"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+authors = [{ name = "Daniel Pepper" }]
+requires-python = ">= 3.11"
+dependencies = ["faker"]
+keywords = ["testing", "factories", "fixtures", "factory_bot"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Framework :: Pytest",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Testing",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+django = ["django"]
+sqlalchemy = ["sqlalchemy >= 2"]
+
+[project.urls]
+Homepage = "https://github.com/dpep/py_factory_bot"
+Issues = "https://github.com/dpep/py_factory_bot/issues"
+Changelog = "https://github.com/dpep/py_factory_bot/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "pytest >= 8.2",
+  "ruff",
+  "django",
+  "sqlalchemy >= 2",
+]
+
+[tool.hatch.version]
+path = "src/factory_bot/__init__.py"
+
+# Allowlist so untracked local files never ship.
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "CHANGELOG.md", "LICENSE.txt", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]
+addopts = ["--import-mode=importlib", "--strict-markers"]
+xfail_strict = true
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+extend-select = ["I", "UP", "B"]

factory_bot-0.0.1/src/factory_bot/__init__.py

@@ -0,0 +1,25 @@
+from ._core import (
+    FactoryError,
+    attributes_for,
+    build,
+    clear_factories,
+    factory,
+    reset_sequences,
+    sequence,
+)
+from ._fake import fake, seed
+
+__author__ = "dpepper"
+__version__ = "0.0.1"
+
+__all__ = [
+    "FactoryError",
+    "attributes_for",
+    "build",
+    "clear_factories",
+    "factory",
+    "fake",
+    "reset_sequences",
+    "seed",
+    "sequence",
+]

factory_bot-0.0.1/src/factory_bot/_core.py

@@ -0,0 +1,210 @@
+import copy
+import difflib
+import inspect
+import itertools
+import os
+import weakref
+
+_registry: dict[str, "_Factory"] = {}
+_sequences: weakref.WeakSet["_Sequence"] = weakref.WeakSet()
+
+
+class FactoryError(Exception):
+    pass
+
+
+def factory(model):
+    """Register the decorated function as a factory for `model`, e.g. @factory(User)."""
+    if _is_body(model):
+        raise FactoryError(
+            f"@factory needs a model: write @factory(User) or @factory(dict) above def {model.__name__}"
+        )
+
+    def register(body):
+        name = body.__name__
+        if not callable(model):
+            raise FactoryError(f"Factory {name!r}: model {model!r} is not callable")
+        if name in _registry:
+            raise FactoryError(
+                f"Factory {name!r} is already defined{_where(_registry[name].body)}"
+            )
+        _registry[name] = _Factory(name, model, body)
+        return body
+
+    return register
+
+
+def build(name, /, *traits, **overrides):
+    fac = _lookup(name)
+    return fac.model(**fac.attributes_for(traits, overrides))
+
+
+def attributes_for(name, /, *traits, **overrides):
+    return _lookup(name).attributes_for(traits, overrides)
+
+
+def sequence(fn):
+    """A value built from a counter that starts at 1, e.g. sequence(lambda n: f"user{n}")."""
+    try:
+        inspect.signature(fn).bind(1)
+    except TypeError:
+        raise FactoryError(
+            f'sequence() takes a function of the counter, e.g. sequence(lambda n: f"user{{n}}"), not {fn!r}'
+        ) from None
+    except ValueError:  # no inspectable signature; trust it
+        pass
+    return _Sequence(fn)
+
+
+def clear_factories():
+    _registry.clear()
+
+
+def reset_sequences():
+    for seq in _sequences:
+        seq.reset()
+
+
+class _Factory:
+    def __init__(self, name, model, body):
+        self.name, self.model, self.body = name, model, body
+        self.attributes = {}
+        self.traits = {}
+        body(_Definition(self, self.attributes))
+
+    def attributes_for(self, traits, overrides):
+        return _Evaluator(self.name, self.definitions(traits), overrides).attributes()
+
+    def definitions(self, traits):
+        definitions = dict(self.attributes)
+        for trait in traits:
+            if trait not in self.traits:
+                raise FactoryError(
+                    f"Factory {self.name!r} has no trait {trait!r}.{_suggest(trait, self.traits)}"
+                    f" Traits: {', '.join(self.traits) or '(none)'}"
+                )
+            definitions |= self.traits[trait]
+        return definitions
+
+
+class _Sequence:
+    def __init__(self, fn):
+        self.fn = fn
+        self.reset()
+        _sequences.add(self)
+
+    def reset(self):
+        self.counter = itertools.count(1)
+
+    def next(self):
+        return self.fn(next(self.counter))
+
+
+class _Definition:
+    """The `f` in `def user(f):`. Assigning to it declares an attribute."""
+
+    def __init__(self, factory, attributes):
+        object.__setattr__(self, "_factory", factory)
+        object.__setattr__(self, "_attributes", attributes)
+
+    def __setattr__(self, name, value):
+        self._attributes[name] = value
+
+    def trait(self, body):
+        # Run the body now, once: re-running it per build would restart its sequences.
+        attributes = {}
+        body(_Definition(self._factory, attributes))
+        self._factory.traits[body.__name__] = attributes
+        return body
+
+    def __getattr__(self, name):
+        raise FactoryError(
+            f"Factory {self._factory.name!r}: can't read f.{name} in a definition."
+            f" To use another attribute, take it as a parameter: lambda {name}: ..."
+        )
+
+
+class _Evaluator:
+    """Resolves one build's attributes, each at most once, in dependency order."""
+
+    def __init__(self, factory_name, definitions, overrides):
+        self.factory_name = factory_name
+        self.definitions = definitions
+        self.values = dict(overrides)  # overrides are plain values, never called
+        self.resolving = []
+
+    def attributes(self):
+        names = (self.definitions | self.values).keys()  # declaration order
+        return {name: self.get(name) for name in names}
+
+    def get(self, name, needed_by=None):
+        if name in self.values:
+            return self.values[name]
+        definitions = self.definitions
+        if name not in definitions:
+            raise FactoryError(
+                f"Factory {self.factory_name!r}: {needed_by!r} depends on {name!r}, which is not defined."
+                f"{_suggest(name, definitions)}{_where(definitions[needed_by])}"
+            )
+        if name in self.resolving:
+            cycle = " -> ".join([*self.resolving[self.resolving.index(name) :], name])
+            raise FactoryError(
+                f"Factory {self.factory_name!r}: circular dependency: {cycle}"
+            )
+        self.resolving.append(name)
+        try:
+            self.values[name] = self.evaluate(name, definitions[name])
+        finally:
+            self.resolving.pop()
+        return self.values[name]
+
+    def evaluate(self, name, value):
+        if isinstance(value, _Sequence):
+            return value.next()
+        if callable(value):
+            return value(
+                **{dep: self.get(dep, needed_by=name) for dep in _dependencies(value)}
+            )
+        if isinstance(value, (list, dict, set)):
+            return copy.copy(value)
+        return value
+
+
+def _dependencies(fn):
+    # Only required params: fake.paragraph(nb_sentences=3) must not be injected.
+    try:
+        params = inspect.signature(fn).parameters.values()
+    except (TypeError, ValueError):  # some builtins (dict, str) have no signature
+        return []
+    keyword = (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+    return [p.name for p in params if p.kind in keyword and p.default is p.empty]
+
+
+def _lookup(name):
+    if name not in _registry:
+        raise FactoryError(f"No factory named {name!r}.{_suggest(name, _registry)}")
+    return _registry[name]
+
+
+def _is_body(model):
+    # Bare @factory hands us the body itself: a function of exactly one required argument.
+    if not inspect.isfunction(model):
+        return False
+    params = list(inspect.signature(model).parameters.values())
+    return (
+        len(params) == 1
+        and params[0].kind is params[0].POSITIONAL_OR_KEYWORD
+        and params[0].default is params[0].empty
+    )
+
+
+def _suggest(name, options):
+    close = difflib.get_close_matches(name, list(options), n=1)
+    return f" Did you mean {close[0]!r}?" if close else ""
+
+
+def _where(fn):
+    code = getattr(fn, "__code__", None)
+    return (
+        f" ({os.path.basename(code.co_filename)}:{code.co_firstlineno})" if code else ""
+    )

factory_bot-0.0.1/src/factory_bot/_fake.py

@@ -0,0 +1,8 @@
+from faker import Faker
+
+fake = Faker()
+
+
+def seed(value):
+    """Seed `fake` so a test's generated data is reproducible."""
+    fake.seed_instance(value)

factory_bot-0.0.1/tests/conftest.py

@@ -0,0 +1,9 @@
+import pytest
+
+from factory_bot import clear_factories, reset_sequences
+
+
+@pytest.fixture(autouse=True)
+def clean_registry():
+    clear_factories()
+    reset_sequences()

factory_bot-0.0.1/tests/support/models.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class User:
+    first_name: str = ""
+    last_name: str = ""
+    email: str | None = None
+    username: str = ""
+    admin: bool = False
+    tags: list = field(default_factory=list)

factory_bot-0.0.1/tests/test_attributes_for.py

@@ -0,0 +1,23 @@
+from support.models import User
+
+from factory_bot import attributes_for, factory, sequence
+
+
+def test_attributes_for_returns_the_resolved_attributes_without_building():
+    @factory(User)
+    def user(f):
+        f.first_name = "John"
+        f.email = lambda first_name: f"{first_name}@example.com"
+        f.username = sequence(lambda n: f"user{n}")
+        f.admin = False
+
+        @f.trait
+        def admin(f):
+            f.admin = True
+
+    assert attributes_for("user", "admin", first_name="Ann") == {
+        "first_name": "Ann",
+        "email": "Ann@example.com",
+        "username": "user1",
+        "admin": True,
+    }

factory_bot-0.0.1/tests/test_build.py

@@ -0,0 +1,105 @@
+import pytest
+from support.models import User
+
+from factory_bot import FactoryError, build, factory
+
+
+def test_builds_the_model_from_static_attributes():
+    @factory(User)
+    def user(f):
+        f.first_name = "John"
+        f.last_name = "Doe"
+
+    assert build("user") == User(first_name="John", last_name="Doe")
+
+
+def test_any_callable_taking_kwargs_is_a_model():
+    @factory(dict)
+    def point(f):
+        f.x = 1
+        f.y = 2
+
+    assert build("point") == {"x": 1, "y": 2}
+
+
+def test_a_plain_function_is_a_model_too():
+    def make_point(**kwargs):
+        return kwargs
+
+    @factory(make_point)
+    def point(f):
+        f.x = 1
+
+    assert build("point") == {"x": 1}
+
+
+def test_overrides_win_and_may_add_attributes():
+    @factory(dict)
+    def point(f):
+        f.x = 1
+
+    assert build("point", x=5, z=3) == {"x": 5, "z": 3}
+
+
+def test_an_attribute_called_name_can_be_overridden():
+    @factory(dict)
+    def person(f):
+        f.name = "Ann"
+
+    assert build("person", name="Bea") == {"name": "Bea"}
+
+
+def test_mutable_values_are_not_shared_between_builds():
+    @factory(User)
+    def user(f):
+        f.tags = []
+
+    first, second = build("user"), build("user")
+    first.tags.append("x")
+    assert second.tags == []
+
+
+def test_unknown_factory_suggests_the_closest_name():
+    @factory(User)
+    def user(f):
+        pass
+
+    with pytest.raises(
+        FactoryError, match=r"^No factory named 'usr'\. Did you mean 'user'\?$"
+    ):
+        build("usr")
+
+
+def test_bare_decorator_names_the_fix():
+    with pytest.raises(
+        FactoryError, match=r"@factory needs a model.*@factory\(User\).*def user"
+    ):
+
+        @factory
+        def user(f):
+            pass
+
+
+def test_model_must_be_callable():
+    with pytest.raises(
+        FactoryError, match=r"Factory 'user': model 'User' is not callable"
+    ):
+
+        @factory("User")
+        def user(f):
+            pass
+
+
+def test_duplicate_factory_names_are_rejected():
+    @factory(User)
+    def user(f):
+        pass
+
+    with pytest.raises(
+        FactoryError,
+        match=r"^Factory 'user' is already defined \(test_build\.py:\d+\)$",
+    ):
+
+        @factory(User)
+        def user(f):
+            pass

factory_bot-0.0.1/tests/test_fake.py

@@ -0,0 +1,25 @@
+from faker import Faker
+
+from factory_bot import build, factory, fake, seed
+
+
+def test_fake_is_a_shared_faker_whose_methods_are_lazy_values():
+    @factory(dict)
+    def user(f):
+        f.first_name = fake.first_name
+        f.bio = fake.paragraph  # its parameters all have defaults, so none are injected
+
+    assert isinstance(fake, Faker)
+    users = [build("user") for _ in range(5)]
+    assert len({u["first_name"] + u["bio"] for u in users}) > 1
+
+
+def test_seed_makes_fake_values_reproducible():
+    @factory(dict)
+    def user(f):
+        f.first_name = fake.first_name
+
+    seed(1234)
+    first = [build("user") for _ in range(3)]
+    seed(1234)
+    assert [build("user") for _ in range(3)] == first

factory_bot-0.0.1/tests/test_lazy.py

@@ -0,0 +1,106 @@
+import itertools
+import re
+
+import pytest
+
+from factory_bot import FactoryError, build, factory
+
+
+def test_callables_are_called_on_every_build():
+    counter = itertools.count(1)
+
+    @factory(dict)
+    def ticket(f):
+        f.number = lambda: next(counter)
+
+    assert [build("ticket")["number"] for _ in range(3)] == [1, 2, 3]
+
+
+def test_required_parameters_are_injected_by_name():
+    @factory(dict)
+    def user(f):
+        f.email = lambda first_name, last_name: f"{first_name}.{last_name}@example.com"
+        f.first_name = "Ann"
+        f.last_name = "Lee"
+
+    assert build("user")["email"] == "Ann.Lee@example.com"
+
+
+def test_dependencies_see_overrides():
+    @factory(dict)
+    def user(f):
+        f.first_name = "Ann"
+        f.email = lambda first_name: f"{first_name}@example.com"
+
+    assert build("user", first_name="Bea")["email"] == "Bea@example.com"
+
+
+def test_parameters_with_defaults_are_left_alone():
+    @factory(dict)
+    def post(f):
+        f.domain = "wrong.example"
+        f.body = lambda nb_sentences=3, domain=None: (nb_sentences, domain)
+
+    assert build("post")["body"] == (3, None)
+
+
+def test_a_callable_without_an_inspectable_signature_has_no_dependencies():
+    @factory(dict)
+    def user(f):
+        f.meta = dict
+
+    first, second = build("user"), build("user")
+    assert first["meta"] == {}
+    assert first["meta"] is not second["meta"]
+
+
+def test_overrides_are_never_called():
+    @factory(dict)
+    def job(f):
+        f.run = lambda: "default"
+
+    def callback():
+        pass
+
+    assert build("job", run=callback)["run"] is callback
+
+
+def test_an_undefined_dependency_names_the_attribute_and_suggests_a_fix():
+    @factory(dict)
+    def broken(f):
+        f.first_name = "x"
+        f.email = lambda frist_name: frist_name
+
+    message = (
+        "Factory 'broken': 'email' depends on 'frist_name', which is not defined."
+        " Did you mean 'first_name'?"
+    )
+    with pytest.raises(
+        FactoryError, match=rf"^{re.escape(message)} \(test_lazy\.py:\d+\)$"
+    ):
+        build("broken")
+
+
+def test_a_circular_dependency_shows_the_cycle():
+    @factory(dict)
+    def cyclic(f):
+        f.a = lambda b: b
+        f.b = lambda c: c
+        f.c = lambda a: a
+
+    with pytest.raises(
+        FactoryError, match=r"^Factory 'cyclic': circular dependency: a -> b -> c -> a$"
+    ):
+        build("cyclic")
+
+
+def test_reading_an_attribute_in_a_definition_points_to_injection():
+    with pytest.raises(
+        FactoryError,
+        match=r"Factory 'user': can't read f\.first_name.*lambda first_name:",
+    ):
+
+        @factory(dict)
+        def user(f):
+            f.first_name = "Ann"
+            f.email = f.first_name + "@example.com"

factory_bot-0.0.1/tests/test_package.py

@@ -0,0 +1,5 @@
+import factory_bot
+
+
+def test_version():
+    assert factory_bot.__version__

factory_bot-0.0.1/tests/test_sequences.py

@@ -0,0 +1,48 @@
+import pytest
+
+from factory_bot import FactoryError, build, factory, reset_sequences, sequence
+
+
+def test_a_sequence_counts_up_from_one_per_build():
+    @factory(dict)
+    def user(f):
+        f.username = sequence(lambda n: f"user{n}")
+
+    assert [build("user")["username"] for _ in range(3)] == ["user1", "user2", "user3"]
+
+
+def test_each_sequence_keeps_its_own_count():
+    @factory(dict)
+    def user(f):
+        f.username = sequence(lambda n: f"user{n}")
+        f.code = sequence(lambda n: n * 10)
+
+    build("user")
+    assert build("user") == {"username": "user2", "code": 20}
+
+
+def test_an_override_does_not_advance_the_sequence():
+    @factory(dict)
+    def user(f):
+        f.username = sequence(lambda n: f"user{n}")
+
+    build("user", username="custom")
+    assert build("user")["username"] == "user1"
+
+
+def test_reset_sequences_starts_every_count_over():
+    @factory(dict)
+    def user(f):
+        f.username = sequence(lambda n: f"user{n}")
+
+    build("user")
+    reset_sequences()
+    assert build("user")["username"] == "user1"
+
+
+def test_a_sequence_needs_a_function_of_the_counter():
+    with pytest.raises(
+        FactoryError,
+        match=r"sequence\(\) takes a function of the counter, e\.g\. sequence\(lambda n:",
+    ):
+        sequence("user")

factory_bot-0.0.1/tests/test_traits.py

@@ -0,0 +1,73 @@
+import re
+
+import pytest
+from support.models import User
+
+from factory_bot import FactoryError, build, factory, sequence
+
+
+@pytest.fixture
+def user_factory():
+    @factory(User)
+    def user(f):
+        f.first_name = "John"
+        f.email = lambda first_name: f"{first_name}@example.com".lower()
+        f.admin = False
+
+        @f.trait
+        def admin(f):
+            f.admin = True
+            f.first_name = "Root"
+
+        @f.trait
+        def anonymous(f):
+            f.first_name = "Anon"
+            f.email = None
+
+
+def test_a_trait_overrides_the_factory_and_feeds_dependencies(user_factory):
+    assert build("user", "admin") == User(
+        first_name="Root", email="root@example.com", admin=True
+    )
+
+
+def test_traits_apply_in_order_and_later_wins(user_factory):
+    assert build("user", "admin", "anonymous").first_name == "Anon"
+    assert build("user", "anonymous", "admin").first_name == "Root"
+
+
+def test_overrides_win_over_traits(user_factory):
+    assert build("user", "admin", admin=False, first_name="Jane").admin is False
+
+
+def test_a_trait_body_runs_once_so_its_sequence_keeps_counting():
+    @factory(dict)
+    def user(f):
+        f.username = sequence(lambda n: f"user{n}")
+
+        @f.trait
+        def admin(f):
+            f.username = sequence(lambda n: f"admin{n}")
+
+    assert [build("user", "admin")["username"] for _ in range(3)] == [
+        "admin1",
+        "admin2",
+        "admin3",
+    ]
+
+
+def test_an_unknown_trait_suggests_the_closest_and_lists_them_all(user_factory):
+    message = "Factory 'user' has no trait 'admn'. Did you mean 'admin'? Traits: admin, anonymous"
+    with pytest.raises(FactoryError, match=rf"^{re.escape(message)}$"):
+        build("user", "admn")
+
+
+def test_a_factory_without_traits_says_so():
+    @factory(User)
+    def user(f):
+        pass
+
+    with pytest.raises(
+        FactoryError, match=r"^Factory 'user' has no trait 'admin'\. Traits: \(none\)$"
+    ):
+        build("user", "admin")