DEV Community: Rabbil Yasar Sajal

Why .env.example Gets Out of Sync — and What Actually Fixes It

Rabbil Yasar Sajal — Mon, 24 Aug 2026 21:59:00 +0000

Quick answer

.env.example goes out of sync because it's a plain text file with no way to enforce that it matches your code — nothing runs when a variable is added, removed, or made conditional. The fix isn't a better example file; it's a schema: a single, versioned file that declares what your configuration is actually supposed to be, which a tool then generates the example file from and validates everything else against. In EnvShield, that schema is env.schema.toml — envshield schema sync generates .env.example from it, and envshield schema sync --check fails the moment the two drift, typically wired into a pre-commit hook so it's caught before the commit lands, not after a teammate hits it.

The problem

Open almost any repo's .env.example and you'll find the same story: it was accurate the day someone wrote it, and it's been quietly drifting ever since. A teammate adds STRIPE_WEBHOOK_SECRET to the payment service, the PR gets reviewed for logic, and nobody thinks to update the template — why would they? It's not code. Six weeks later someone clones the repo, copies .env.example to .env, runs the app, and it crashes on a variable the file never mentioned.

Search for this problem and you'll find a lot of people asking variations of the same three questions: how do I keep .env and .env.example in sync, why does .env.example keep missing environment variables, and is there a better way to do environment variable documentation than a hand-maintained text file. This article is about why the file drifts in the first place, and what actually stops it — not just what to rename it.

Why it happens

.env.example isn't badly designed. It's just structurally unable to enforce itself. It's a text file with no relationship to the code that reads the variables it lists, no relationship to the deployment manifest that's supposed to provide them, and no mechanism that runs when either of those changes. Someone has to remember to update it, by hand, every single time — and "someone has to remember" is exactly the kind of process that survives right up until it doesn't.

The result is a file that's simultaneously trusted and untrustworthy. New teammates copy it assuming it's complete. It usually isn't. Not because anyone was careless, but because nothing in the workflow ever made keeping it current cheaper than ignoring it.

What people do about it today

A few common approaches, and where each one runs out:

Manual discipline and code review. Ask reviewers to check for new env vars during PR review. Works until the variable is added inside a conditional branch nobody exercises in the diff, or a reviewer just misses it — which, over enough PRs, is a when, not an if.

A comment or checklist in the README. "Remember to update .env.example when you add a variable." This is a policy, not a mechanism. Policies that depend on memory have the same failure mode as the problem they're meant to solve.

A custom sync script. Some teams write a script that diffs .env against .env.example and fails CI if they don't match. This genuinely helps — it catches drift between two files. What it can't do is tell you a variable is missing from both of them, because it only knows about keys, not requirements. It can't tell you PORT=banana is invalid, and a hand-maintained .env.example has no way to express that a variable is only required when another flag is set — at best it can carry that as a comment someone wrote once; nothing enforces it.

Schema-based .env tooling. This is the right direction, and it's not just EnvShield's idea — Varlock, for one, takes the same core position: a committed schema, not a hand-maintained example file, should be the source of truth, and it adds real things on top of that (type-safe resolution, automatic secret redaction in logs). If your stack is JS/TS-centric and your concern is specifically keeping .env files honest inside that ecosystem, it's worth a look. EnvShield takes the same schema-as-contract idea further in a different direction: the same schema also validates against a Docker Compose or Kubernetes manifest, a second service written in a different language, and the actual git history of what the contract used to require — not just a local .env file. That's the gap the rest of this article is about.

The fix: a schema as the source of truth, not a description of one

The actual fix isn't a better .env.example. It's removing .env.example from being anyone's source of truth at all, and replacing it with something that can be validated instead of just read.

Concretely: a schema — a single, versioned, machine-readable file — declares what a project's configuration is supposed to be. Everything else (a local .env, a generated template, a deployment manifest) gets checked against it. Nobody maintains the template by hand anymore, because it isn't a document anyone writes — it's an output.

Here's what that looks like as env.schema.toml, EnvShield's implementation of the idea — this article stays focused on the sync problem specifically; for the fuller walkthrough of the contract itself, see The End of .env Chaos:

[DATABASE_URL]
description = "PostgreSQL connection string"
type = "url"
secret = true

[PORT]
description = "Port the API listens on"
type = "port"
defaultValue = "8000"

[LOG_LEVEL]
description = "Controls the application's log verbosity"
defaultValue = "info"

[STRIPE_SECRET_KEY]
description = "Stripe secret key -- only needed once payments are turned on"
secret = true
requiredIf = { var = "PAYMENTS_ENABLED", equals = "true" }

Notice DATABASE_URL has neither a default nor a condition — that's what makes it required. There's no separate required = true field to remember: a variable is required unconditionally unless a defaultValue waives it or a requiredIf makes it conditional on another variable's value. type gives check something to actually validate against (PORT=banana fails, rather than surfacing three services downstream). requiredIf is what a static example file structurally can't express — STRIPE_SECRET_KEY is optional while PAYMENTS_ENABLED=false, and becomes required the moment that flag flips, in any environment.

The schema is not the example file

This is the distinction that matters most, because collapsing it back into "just a nicer .env.example" undoes the whole point: env.schema.toml is the contract. .env.example is a rendering of it.

$ envshield schema sync

Generating .env.example from schema...
✓ Successfully created/updated .env.example!

Next step:
  Review the updated template, then commit it.
  If it added a variable you need locally, run 'envshield setup'.

That command generates the actual file:

# This file was auto-generated by EnvShield on <generation timestamp>
# It is generated from the contract defined in env.schema.toml.
# DO NOT EDIT THIS FILE MANUALLY.

# PostgreSQL connection string
# secret
DATABASE_URL=

# Port the API listens on
PORT=8000

# Controls the application's log verbosity
LOG_LEVEL=info

# Stripe secret key -- only needed once payments are turned on
# secret; required if PAYMENTS_ENABLED = "true"
STRIPE_SECRET_KEY=

Edit that file by hand and the next schema sync silently overwrites your change — which is correct, not a bug, because once a schema exists, .env.example is generated output, not something anything else reads. (An existing .env.example can still be one of the inputs envshield init reads to seed a schema in the first place, on a project that doesn't have one yet — the "output, not source" rule is about what happens after the schema exists, not before.) The variable that actually stops drift is --check:

$ envshield schema sync --check
✓ '.env.example' is in sync with schema.

Add a field to the schema without regenerating the template, and the same command tells you exactly what's missing instead of letting it slip through:

$ envshield schema sync --check
✗ Missing from '.env.example': NEW_FEATURE_FLAG (run 'envshield schema sync' to regenerate it)

Wire that into envshield hook install and it runs automatically before a commit lands — but only for a schema you actually staged, so it never blocks a commit that didn't touch configuration.

What `secret = true` actually does — and doesn't

Worth being precise here, because it's the field people most often over-assume about. secret = true tells EnvShield a field is sensitive. It does not, and structurally cannot, hold the value — the schema only ever describes the shape of configuration, never real values. The actual key lives in your local, git-ignored .env, nowhere else.

What the flag buys you: .env.example shows # secret instead of a value, and any code EnvShield generates treats the field as sensitive too. That's the feature, in full. EnvShield doesn't store secret values, doesn't retrieve them from anywhere, and isn't where you'd go to rotate one. If you need an actual vault, that's what 1Password, HashiCorp Vault, or AWS Secrets Manager are for — this is a contract describing a secret, not a place to keep one.

Validating that the contract actually holds

Once the schema exists, check is what enforces it against a real local file:

$ envshield check

Validating .env against schema...
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status        ┃ Variable Name ┃ Source                             ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Invalid Value │ PORT          │ must be a port number from 1-65535 │
└───────────────┴───────────────┴────────────────────────────────────┘

Suggestion: Run 'envshield setup' to fill in missing/blank values or fix invalid ones.

This is the check a text file can't do. A stale .env.example never had an opinion on whether PORT=banana is valid — it doesn't know what a port is. A schema does, because type is a real constraint, not a comment.

The next layer: what about variables nobody declared at all?

Everything so far assumes someone remembered to add the variable to the schema in the first place. That's a real gap on its own — a schema you have to remember to update by hand has just moved the discipline problem one level up, not solved it. That's a distinct problem from the one this article is about, and EnvShield has a separate command for it (envshield undeclared, which catches a variable your code just started reading that the schema doesn't know about yet) — worth its own explanation rather than a paragraph tacked onto this one.

When this approach makes sense — and when it doesn't

A schema is overhead you don't need for a two-variable prototype script you'll delete next week, or a project with exactly one contributor who already holds the whole configuration in their head. In those cases, a plain .env and a five-minute memory are genuinely fine — don't add a contract to solve a problem you don't have yet.

It starts paying for itself once any of these are true: more than one person touches the project, configuration differs by environment (local vs. staging vs. production), or a deployment manifest needs to independently agree with the application about what it requires. That's also roughly where a hand-maintained .env.example starts failing anyway — the timing isn't a coincidence.

A practical migration path

envshield init, whether or not you already have real configuration. It builds env.schema.toml from an existing .env, .env.example, or a Python config module when one of those exists — and falls back to a framework-aware template on a genuinely fresh project with none of that yet. Either way, it also writes envshield.yml, registers a deployment manifest if it finds one, updates .gitignore, and offers to install Git hooks.
Review the generated schema. Mark real secrets with secret = true, add defaultValue for anything genuinely optional, and requiredIf for anything conditional. This is the one manual step, and it only happens once per variable, not once per drift.
envshield schema sync, then commit both env.schema.toml and the generated .env.example together.
envshield check against your own local file to confirm nothing's actually missing or malformed right now.
envshield hook install so a schema change without a regenerated template gets caught before it's committed, not after someone else hits it.

None of this requires believing configuration is glamorous. It requires believing that "what does this project actually need to run" shouldn't depend on someone remembering to update a text file.

pip install envshield

GitHub · Docs · Website

Want to simplify how you manage your env files and secrets?

Rabbil Yasar Sajal — Wed, 24 Sep 2025 15:05:06 +0000

Rabbil Yasar Sajal

Sep 17 '25

The End of .env Chaos: How a Configuration Contract Fixes Environment Variables

#opensource #devops #python #configuration

5 min read

Read about the how EnvShield is compared to TruffleHog

Rabbil Yasar Sajal — Wed, 24 Sep 2025 15:02:54 +0000

Rabbil Yasar Sajal

Sep 22 '25

EnvShield vs. TruffleHog: Configuration Contracts vs. Secret Scanning

#opensource #devops #security #cli

3 min read

[Boost]

Rabbil Yasar Sajal — Wed, 24 Sep 2025 15:01:58 +0000

Rabbil Yasar Sajal

Sep 22 '25

EnvShield vs. TruffleHog: Configuration Contracts vs. Secret Scanning

#opensource #devops #security #cli

3 min read

EnvShield vs. TruffleHog: Configuration Contracts vs. Secret Scanning

Rabbil Yasar Sajal — Mon, 22 Sep 2025 15:26:46 +0000

TL;DR

EnvShield is a configuration-contract engine (env.schema.toml) — it validates configuration, discovers undeclared variables, reviews schema changes across git revisions, and validates deployment manifests. Secret scanning is one supporting check inside it, not the product.
TruffleHog is a dedicated secret-scanning engine — 800+ credential detectors, deep git-history scanning across many platforms, live verification against provider APIs.
These solve different problems. Use EnvShield to keep your configuration contract enforced day-to-day; reach for TruffleHog when you need a deep, org-wide secret-history audit.

Install EnvShield →

Why this comparison keeps coming up

Both tools get mentioned in the same "how do I stop leaking secrets" conversations, so it's a fair question whether they compete. They don't, for a simple reason: they're built to answer different questions.

TruffleHog answers: is there a real, exposed credential anywhere in this codebase or its history?
EnvShield answers: does this project's configuration actually match what it declares it needs?

Secret exposure is one specific way a project's configuration can go wrong. It's not the only way, and it's not EnvShield's reason for existing — envshield scan catches hardcoded secrets and undeclared variables as a supporting check alongside the configuration contract, not the product itself.

What each one actually does

	EnvShield	TruffleHog
Primary problem	Configuration contract — does your config match what the project declares it needs	Secret detection — find exposed, active credentials in code and history
Schema/contract (`env.schema.toml`)	Yes — this is the core artifact	No concept of a configuration schema
Local configuration validation	Yes (`check`, `doctor`, `setup`)	No
Undeclared env-var detection	Yes (`undeclared`, `scan`)	No
Schema diff across git revisions	Yes (`schema diff`)	No
Deployment manifest validation (Compose/K8s)	Yes (`check`)	No
Secret scanning (pattern-based)	Yes — supporting check (`scan`)	Yes — this is the core product
Git/history scanning	No	Yes — full git history, across GitHub, GitLab, Slack, and more
Live credential verification	No	Yes — checks whether a found credential is still active against the provider's real API

TruffleHog's own numbers put this in perspective: 800+ credential detectors, most supporting active verification against the provider's API. That's a different scale of investment in secret detection specifically than scan is trying to be — EnvShield isn't competing with it there, and doesn't need to.

Where they genuinely overlap

Both can flag a hardcoded secret sitting in your current working tree. That's the actual overlap — one row in the table above. Everything else is either EnvShield-only (the whole configuration-contract side) or TruffleHog-only (history scanning, live verification, detector breadth).

Example

TruffleHog — scan a repo's full history for verified, active secrets:

trufflehog git https://github.com/org/repo.git

EnvShield — validate configuration against the contract, and check for undeclared reads in the current tree:

envshield check
envshield scan

Neither command is a substitute for the other's actual job.

Using both

If you want deep, verified secret-history auditing, TruffleHog is built for exactly that, and scan doesn't try to replicate it. If you want your configuration itself — types, requiredness, what's declared versus what code actually reads, what changed in a PR — to be a real, checkable contract instead of a folder of assumptions, that's what EnvShield is for. Running both isn't a "layered security" strategy so much as just using two tools for two different jobs, the same way a linter and a type checker don't compete for the same role.

Takeaway

Use EnvShield to keep your configuration contract enforced day-to-day. Reach for TruffleHog when you specifically need deep, org-wide secret-history auditing. Neither replaces the other, and neither is trying to.

pip install envshield

EnvShield on GitHub · Website · Docs

The End of .env Chaos: How a Configuration Contract Fixes Environment Variables

Rabbil Yasar Sajal — Wed, 17 Sep 2025 14:27:21 +0000

Let's be honest: .env.example files have a reputation problem. Everyone knows they're important and nobody quite trusts them. Mine's usually out of date within a month — missing whatever variable got added in a PR nobody reviewed for configuration changes.

But here's a distinction worth making up front, because getting it wrong is exactly why .env.example stays broken: .env itself isn't the problem. A key-value file is a perfectly fine way to hold configuration at runtime. The actual problem is that nothing declares, in one place, what a project's configuration is supposed to look like. Requirements are implicit — they live in application code, in a deployment manifest, in a .env.example someone wrote by hand once, and in a senior developer's memory of "oh, you also need STRIPE_SECRET_KEY if payments are on." None of those four places are required to agree with each other. They usually do, right up until they don't.

That's what a configuration contract actually fixes — not "cleaner env files," but one real, versioned, checkable description of what a project needs, that everything else (code, deployment manifests, a new teammate's local setup) gets validated against instead of just trusted.

`env.schema.toml`: the contract, not a description of one

EnvShield's answer is a file named env.schema.toml, committed to git, next to the code it configures:

[DATABASE_URL]
description = "PostgreSQL connection string"
type = "url"
secret = true

[PORT]
description = "Port the API listens on"
type = "port"
defaultValue = "8000"

[LOG_LEVEL]
description = "Controls the application's log verbosity"
defaultValue = "info"

[STRIPE_SECRET_KEY]
description = "Stripe secret key -- only needed once payments are turned on"
secret = true
requiredIf = { var = "PAYMENTS_ENABLED", equals = "true" }

Five fields doing five different jobs:

type — the value's shape (string, int, float, bool, port, url, email). check, setup, and doctor all enforce it — PORT=banana fails validation, not at runtime three services downstream.
defaultValue — what setup writes automatically if nobody provides one. The variable still has to be present in the local file; the default just means check stops complaining once it is.
description — shown in setup's prompt and copied into any generated config code.
secret — marks a field sensitive. More on exactly what that does below, because it's easy to over-assume.
requiredIf — makes a field required only when another variable's value says it should be. STRIPE_SECRET_KEY above is optional while PAYMENTS_ENABLED=false, and becomes required the moment that flag flips, in any environment.

Notice DATABASE_URL has neither a default nor a condition — that's what makes it required. There's no separate required = true field to remember to set: a variable is required unconditionally unless a defaultValue waives it or a requiredIf makes it conditional.

What `secret = true` actually does (and doesn't)

Worth being precise here, since it's easy to read past: secret = true tells EnvShield this field is sensitive. It does not, and structurally cannot, hold the value itself — the schema only ever describes the shape of your configuration, never the actual values. The real key lives in your local, git-ignored .env, nowhere else.

What the flag buys you: setup masks your keystrokes when prompting for it, import never guesses a real value into the committed schema, and any code EnvShield generates treats the field as sensitive too. That's the whole feature. EnvShield doesn't store secret values, doesn't retrieve them from anywhere, and isn't where you'd go to rotate one. If you need an actual secrets vault, that's what 1Password, HashiCorp Vault, or AWS Secrets Manager are for. EnvShield's job is making sure the contract around a secret is honest, not holding the secret itself.

`env.schema.toml` vs. `.env.example`

This is the distinction the rest of this article depends on: .env.example is a representation of the contract. env.schema.toml is the contract.

envshield schema sync

generates .env.example straight from the schema — documentation for a human skimming the repo, not something EnvShield itself reads back. Edit it by hand, and the next schema sync overwrites your change, because it's an output, not a source. Every command that actually validates or enforces anything — check, setup, doctor, undeclared, schema diff, generate — reads env.schema.toml directly. If you've ever watched a .env.example drift from reality within a month, this is why: it never had a mechanism to stay honest on its own. envshield hook install wires a pre-commit check (schema sync --check) that catches a schema edited without regenerating its template — but that's something you opt into, not something that happens automatically just because a schema exists.

One contract, several workflows

Every command below reads the same file — none of them invent their own idea of what your configuration is supposed to be:

env.schema.toml
     ↓
validation · discovery · documentation · onboarding · review · deployment checks

envshield init — builds the schema from your real, existing config (a .env, a Python config module, or a deployment manifest) if one exists, or a framework-aware template if it doesn't.
envshield setup — interactive onboarding: prompts for whatever's missing, masks secret input, writes a local file.
envshield check — validates a local file, or a Docker Compose or Kubernetes manifest, against the schema.
envshield schema sync — regenerates .env.example from the schema.
envshield undeclared — catches a variable your code just started reading that the schema doesn't know about yet.
envshield schema diff — compares the contract itself across two git revisions, classified by impact (breaking, security-sensitive, informational).

A concrete example: catching a variable before it's committed

Say this line shows up in app/main.py:

analytics_key = os.getenv("ANALYTICS_KEY")

Nobody's added ANALYTICS_KEY to env.schema.toml. It hasn't even been committed yet. Running:

$ envshield undeclared

┌────────────────┬─────────────┬──────┬───────────┬──────────────────────┐
│ Variable       │ File        │ Line │ Access    │ Contract status      │
├────────────────┼─────────────┼──────┼───────────┼──────────────────────┤
│ ANALYTICS_KEY  │ app/main.py │ 42   │ os.getenv │ missing declaration  │
└────────────────┴─────────────┴──────┴───────────┴──────────────────────┘

By default, undeclared compares your working tree against HEAD — including uncommitted and untracked files — so this is caught before git add, not after a teammate hits it in staging.

scan does something related but broader: it inventories every currently-undeclared read across the whole codebase in one pass, alongside hardcoded-secret detection — useful for a first audit of an existing project. undeclared's job is narrower and more precise: what's new since a given revision, which is what makes the example above possible.

Deployment manifests get checked too

The same schema also validates the manifest that actually deploys a service, not just a local file:

envshield check docker-compose.yml
envshield check k8s/deployment.yaml --container api

Docker Compose's ${VAR}/${VAR:-default} interpolation is resolved; Kubernetes Deployments, StatefulSets, DaemonSets, Jobs, CronJobs, and bare Pods are supported, including multi-document manifests. A handful of narrower cases aren't handled yet — the no-colon ${VAR-default} Compose form, Kubernetes secretKeyRef/configMapKeyRef matched by key rather than env-var name, envFrom.prefix. None of them produce a false-clean on a genuinely missing required variable; they're just not resolved yet.

The takeaway

None of this requires believing configuration is glamorous. It requires believing that "what does this project actually need to run" shouldn't be an oral tradition. A schema doesn't add a sixth place to keep configuration description in sync by hand — it gives the other five (code, .env, .env.example, the deployment manifest, and whatever a teammate remembers) something to actually be checked against.

pip install envshield

GitHub · Docs · Website

Django: Testing The What, Why and How. (Code)

Rabbil Yasar Sajal — Mon, 05 Jul 2021 11:49:03 +0000

This is a continuation of two part series, please check out part-1 to look at the theoretical part of testing.

Coverage
Testing Models
Testing Views
Testing Forms
Next Topics To Cover
Conclusion

In this blog we will be looking at how to start with testing and later on how to implement.

Our project setup

Coverage

First we need to know what needs to be tested. As I said before, there is no need to test Django' vanilla model or Django ORM and python's in-built functions.
This is where coverage comes in handy, it is a convenient way for a beginner to find out the functions we need to test.

How to setup coverage

Testing Models

let's open up index.html in our newly created htmlscov folder in our project:

book-library > htmlscov > index.html

We will see something like this:

Let's go to our catalog/models.py.

The red line shows the line we need to test and the percentage represents how much code has been covered with testing.

Considering our Book model:

class Book(models.Model):
    """Model representing a book
    """
    title = models.CharField(max_length=200)
    author = models.ForeignKey('Author', on_delete=models.SET_NULL, null=True)
    summary = models.TextField(
        max_length=1000, help_text='Enter a brief description of the book')
    isbn = models.CharField('ISBN', max_length=13, unique=True,
                            help_text='13 Character <a href="https://www.isbn-international.org/content/what-isbn">ISBN number</a>')
    genre = models.ManyToManyField(Genre, help_text='Select a genre for this book', related_name='books')

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        """Returns the url to access a detail record for this book.
        """
        return reverse('book-detail', args=[str(self.id)])

Test Model Implementation

class TestModels(TestCase):
    @classmethod
    def setUpTestData(self):
        thriller = Genre.objects.create(name='thriller')
        scifi = Genre.objects.create(name='scifi')
        book = Book.objects.create(
            title='test title',
            summary='test summary',
            isbn='test isbn',
        )
        book.genre.set([thriller.pk, scifi.pk])

   def test_book_has_genre(self):
        """checks for genres in book
        """
        book = Book.objects.first()
        self.assertEqual(book.genre.count(), 2)

    def test_book_str(self):
        """Checks str for book
        """
        book = Book.objects.first()
        self.assertEqual(str(book), "test title")

    def test_book_absolute_url_with_200(self):
        book = Book.objects.first()
        self.assertEqual(book.get_absolute_url(), '/catalog/book/1')
        response = self.client.get(book.get_absolute_url())
        self.assertEqual(response.status_code, 200)

Testing str

First we setup our data and then we test for the str representation.

    def test_book_str(self):
        """Checks str for book
        """
        book = Book.objects.first()
        self.assertEqual(str(book), "test title")

One thing to note is the test method name should always start with test_ and it should be precise so that one can understand what the test is about. However, in cases where you feel that the naming may not be precise or meaningful make sure to use docstring to explain what it is supposed to do.

Testing Many To Many

    def test_book_has_genre(self):
        """checks for genres in book
        """
        book = Book.objects.first()
        self.assertEqual(book.genre.count(), 2)

We assigned two genres for our book when we were creating our book. We are simply checking for the count of genres in the book, which tells us that the genres have been assigned successfully.

Testing Absolute Url

    def test_book_absolute_url_with_200(self):
        book = Book.objects.first()
        self.assertEqual(book.get_absolute_url(), '/catalog/book/1')
        response = self.client.get(book.get_absolute_url())
        self.assertEqual(response.status_code, 200)

In our Book model we have a method called get_absolute_url which gets the information of a single book. We check if the status code is 200 and the get_absolute_url method actually is the correct url.

Testing Views

To validate our views we will make use of Django's test client.
Note: This is not strictly "unit test". It is actually quite difficult to write independent unit test for Django view code.

We can check for multiple things in our views but these are some common ones.

Check if only the logged in user can authorize your view (If user needs to be logged in to access).
Check if the correct user can authorize your view.
Check if the both GET and POST is working the way it should.
Check for the validation you may have implemented.

We will refer to our index view for our testing.

from .models import Book, Author, BookInstance, Genre
from django.contrib.auth.decorators import login_required

@login_required(login_url='/login/')
def index(request):
    """View function for home page of site."""

    # Generate counts of some of the main objects
    num_books = Book.objects.all().count()
    num_instances = BookInstance.objects.all().count()

    # Available books (status = 'a')
    num_instances_available = BookInstance.objects.filter(status__exact='a').count()
    num_authors = Author.objects.count()

    # Number of visits to this view, as counted in the session variable.
    num_visits = request.session.get('num_visits', 0)
    request.session['num_visits'] = num_visits + 1

    context = {
        'num_books': num_books,
        'num_instances': num_instances,
        'num_instances_available': num_instances_available,
        'num_authors': num_authors,
        'num_visits': num_visits,
    }

    # Render the HTML template index.html with the data in the context variable
    return render(request, 'index.html', context=context)

Test View Implementation

from django.test import TestCase
from catalog.models import Author
from django.urls import reverse
from django.contrib.auth.models import User
from model_bakery import baker


class IndexViewTest(TestCase):
    @classmethod
    def setUpTestData(cls):
        User.objects.create_user(username='test_user', password='test_password')
        books = baker.make('catalog.Book', _quantity=10)

    def test_view_deny_anonymous(self):
        """Test the view for unauthenticated user if unauthenticated will redirect to login page
        """
        response = self.client.get('/catalog/')
        self.assertRedirects(response, '/login/?next=/catalog/')
        response = self.client.post('/catalog/')
        self.assertRedirects(response, '/login/?next=/catalog/')

    def test_view_url_accesible_by_name(self):
        """Test view is accesible by the reverse method
        """
        self.client.login(username='test_user', password='test_password')
        response = self.client.get(reverse('index'))
        self.assertEqual(response.status_code, 200)
        response = self.client.post(reverse('index'))
        self.assertEqual(response.status_code, 200)

    def test_view_uses_correct_template_(self):
        """Test view is using correct template
        """
        self.client.login(username='test_user', password='test_password')
        response = self.client.get(reverse('index'))
        self.assertEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'index.html')

    def test_view_has_context_num_books(self):
        self.client.login(username='test_user', password='test_password')
        response = self.client.get(reverse('index'))
        self.assertEqual(response.status_code, 200)
        self.assertTrue('num_books' in response.context)
        self.assertEqual(response.context['num_books'], 10)

Deny Unauthorized User

    def test_view_deny_anonymous(self):
        """Test the view for unauthenticated user if unauthenticated will redirect to login page
        """
        response = self.client.get('/catalog/')
        self.assertRedirects(response, '/login/?next=/catalog/')
        response = self.client.post('/catalog/')
        self.assertRedirects(response, '/login/?next=/catalog/')

We are checking if the unauthenticated user is being denied and redirected to the login page.

URL Is Accessed By Name

    def test_view_url_accessible_by_name(self):
        """Test view is accessible by the reverse method
        """
        self.client.login(username='test_user', password='test_password')
        response = self.client.get(reverse('index'))
        self.assertEqual(response.status_code, 200)
        response = self.client.post(reverse('index'))
        self.assertEqual(response.status_code, 200)

We check if the reverse method is working and gets us a status code 200 for both GET and POST method.

Correct Template Usage

    def test_view_uses_correct_template_(self):
        """Test view is using correct template
        """
        self.client.login(username='test_user', password='test_password')
        response = self.client.get(reverse('index'))
        self.assertEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'index.html')

This checks if the correct template is being used by using assertTemplateUsed method.

Test `num_books`

    def test_view_has_context_num_books(self):
        self.client.login(username='test_user', password='test_password')
        response = self.client.get(reverse('index'))
        self.assertEqual(response.status_code, 200)
        self.assertTrue('num_books' in response.context)
        self.assertEqual(response.context['num_books'], 10)

In this method we test if the number of books are assigned correctly. We use model-bakery here to create 10 Book instances.

Testing Forms

Forms are something that can be easily unit tested. We can test for the validation in forms. They accept dictionary of values, validate it and return either errors or cleaned data.
In our project we do not have a form, so let's make one for this tutorial's sake.

from django import forms
from .models import Book


class AddBookForm(forms.ModelForm):
    class Meta:
        model = Book
        fields = ["title"]

    def clean_title(self):
        title = self.cleaned_data['title']
        if not title:
            return title
        if not title[0].isupper():
            self.add_error("title", "Should start with an uppercase")
        if title.endswith("."):
            self.add_error("title", "Should not end with a full stop")

        return title

We included some validation in our model which we will be testing.

Our testing would look something like this.

from django.test import TestCase
from catalog.forms import AddBookForm


class AddBookFormTests(TestCase):
    def test_title_starting_lowercase(self):
        form = AddBookForm(data={"title": "a lowercase title"})

        self.assertEqual(
            form.errors["title"], ["Should start with an uppercase"]
        )

    def test_title_ending_full_stop(self):
        form = AddBookForm(data={"title": "A stopped title."})

        self.assertEqual(
            form.errors["title"], ["Should not end with a full stop"]
        )

    def test_title_with_ampersand(self):
        form = AddBookForm(data={"title": ""})

        self.assertEqual(
            form.errors["title"], ["This field is required."]
        )

As we can see in forms we mainly test for validations. If we want to add some sort of integration tests alongside unit test we could check the validation by using using client doing something like this:

    def test_title_starting_lowercase(self):
        response = self.client.post(
            "/books/add/", data={"title": "a lowercase title"}
        )

        self.assertEqual(response.status_code, HTTPStatus.OK)
        self.assertContains(
            response, "Should start with an uppercase letter", html=True
        )

Next Topics To Cover

I have tried to cover as much as possible in this series but there are tons of things out there when it comes to testing. I will try to cover these topics in my upcoming blogs. A short list includes:

Continuous Integration: Automatically run all tests whenever there a new commit is made. It can be done using GitHub Actions, Travis CI, Circle CI.
Mock: It is an act of replacing part of the application you are testing with a dummy version.
Pytest: It is a testing framework just like unittest. We can also use this instead of unittest
Model Bakery: We saw a small implementation of this in our project but there is more to discuss.
TDD: Test Driven Development, this is actually quite an advance topic which takes a while to get used to, but once you start doing and understand the benefits, you will never want to go back.

Conclusion

To conclude, there is not any concrete way to write your tests. It depends on the project you are working on or the company you are working at. Everyone can have their own way of testing their codes.

The final advice I can give you is, do not be scared of writing tests. Yes, it can be intimidating at first but once you start writing tests you will understand your codes better, it will stimulate to question yourself to think about all the cases where your program can go wrong making you a better programmer.

So this is it for today, if you have any question regarding this please do mention it in the comment or if you have any other questions please do not hesitate to contact me at the following platforms I am available on twitter, GitHub, LinkedIn

Django: Testing The What, Why and How (Theory).

Rabbil Yasar Sajal — Fri, 18 Jun 2021 14:17:50 +0000

A website cannot be perfect as it is nearly impossible for a website to run perfectly the first time without errors. As the project gets large it becomes hard for all the developers to keep track of all the changes; one single change in an existing component can make the whole project to break. This is why it is very essential to test every single functionality.

Table Of Content

Types Of Testing
What Should Be Tested
Our Testing Project
Structure
Third Party Packages
- coverage
Django Package
- client
Testing
- TestCase
- How To Run A Test
Next

Types Of Testing

Unit and Integration testing are two main types of testing.

Unit Tests are isolated tests responsible for only one functionality.
Integration Tests are aimed at mimicking the user behavior, usually combined with multiple functions to make sure they behave correctly.

As Unit Tests are small they should be written all the time. These tests are easy to debug. The more you write these, the lesser you will likely to write integration testing. However, sometimes it is essential to run integration testing.

What Should Be Tested

If something can break, it should be tested. These includes models, views, forms, templates, validators and so on.
Each test should be focused on testing one functionality.
It should run whenever a code is being PUSHed or PULLed from a repo in the staging environment, before PUSHing to production.

That being said if the code in question is a builtin django or python function/library, don't test it. For example datetime or model fields. The only time you test something if the function or code is written by you.

Our Testing Project

In this tutorial we will be using a very basic project book-library.
To set up the project, first we will need to clone the repo.

git clone https://github.com/rabbilyasar/book-library.git

Install virtualenv if not installed already

pip install virtualenv

activate our virtualenv

source env/bin/activate

install the packages in our requirements.txt

pip install -r requirements.txt

asgiref==3.3.4
autopep8==1.5.7
coverage==5.5
Django==3.2.4
mccabe==0.6.1
pycodestyle==2.7.0
pytz==2021.1
sqlparse==0.4.1
toml==0.10.2

Migrate our database

python manage.py migrate

Structure

When you create a django app it includes a test.py file that you can use to write your tests, however, I prefer to create a module called tests and have separate files for our models, forms, views.
Note: If the project gets big it gets hard to maintain in this structure. Another way of doing would be to have a folder for models, views and forms and create file for each view or model.
We would be following the following structure for our project.

└── app_name
    └── tests
        ├── __init__.py
        ├── test_forms.py
        ├── test_models.py
        └── test_views.py

By default django's unittest module uses its builtin-test-discovery. It will discover tests under the current directory with filename pattern test*.py. For our current structure to work we will have to delete our existing tests.py file which has been provided by our django app.

Third Party Packages

coverage: It can be used to have a rough overview of a project's total test coverage. It is a remarkable tool for any beginner as it can give you suggestion on what needs to be tested.
mock: This is a utilitarian tool for isolating part of your code that are not critical to the test you are writing.
model-bakery: This is a fine tool for creating fixtures for testing. We will go through some usage and examples in the next blog.

Coverage

Let's a take a look at coverage and see how we can use it.
To run coverage inside a project:
Install coverage.

pip install coverage

After every time you add some code to your application run this.

coverage run --omit='*/venv/*' manage.py test

If you want to see more details you can add -v flag. In this case it is using verbosity level 2.

coverage run manage.py test -v 2

After running it once we can can get a coverage report using:

coverage report

We can also generate an HTML report in a new folder called htmlcov

coverage html

Django Package

Django's default framework for testing is Python's standard library module unittest. Despite the name this module can be used for both unit test and integration test. There are other modules like pytest, which has it's own benefits and drawbacks on which we will focus later.

Client

Django's test client is an amazing tool which can be used for integration testing. It can simulate GET and POST requests on a URL and one can observe the response. Test Client.

Testing

TestCase

Django provides us with few base classes (SimpleTestCase, LiveServerTestCase, TransactionTestCase, TestCase). You can derive your test class from any of the base classes and have your own method which will test for a specific functionality.

class YourTestClass(TestCase):
    def setUp(self):
        # Setup run before every test method.
        pass

    def tearDown(self):
        # Clean up run after every test method.
        pass

    def test_something_that_will_pass(self):
        self.assertFalse(False)

    def test_something_that_will_fail(self):
        self.assertTrue(False)

The best base class for most tests is django.test.TestCase. This creates a clean database before its tests are run, and runs every test function in its own transaction. The test client can be derived from this. TestCase provides us with an additional method setUpTestData along with setUp for setting up our data.

setUp(): It is called before every test method. This is useful when creating object that will need modifying before each test method.
setUpTestData(): This is called once before running the whole test. You use this one when you know the data you will create in this method will be the same for every test method. As this is run once for every test class, it is faster than setUp().

The tearDown() method is not very useful when it comes to test that involves database. Moreover TestCase does a full database flush at the start of a new test, so it will take care of the teardown for you.

We have some test methods provided to us by unittest, which can be used to test the condition of our code. Some standard assertions are:

AssertTrue: Checks if the condition is true.
AsserFalse: Checks if the condition is false.
AssertEqual: Checks if the condition is equal.

These are some of the python specific assert methods:
python unittest assert

Django specific assert methods:
django unittest assert

How To Run A Test

To run all the test in the project use the command:

python manage.py test

This will discover all files with the pattern test*.py under the directory and run all tests defined.
If we want to show more test information we can change the verbosity like below:

python manage.py test --verbosity 2

Note: Allowed verbosity levels are 0,1,2 and 3, the default being 1.
To run a specific test:

# Run the specified module
python3 manage.py test app.tests

# Run the specified module
python3 manage.py test app.tests.test_models

# Run the specified class
python3 manage.py test app.tests.test_models.YourTestClass

# Run the specified method
python3 manage.py test app.tests.test_models.YourTestClass.your_test_method

In the next part of our series we will get our hands dirty and will see how we can implement unit testing to our book-library.

If you like what I write and want to support me and my work, please follow me on twitter, GitHub, LinkedIn

How To Deploy Django App To Heroku- The Simple Way

Rabbil Yasar Sajal — Wed, 02 Jun 2021 14:06:14 +0000

Have you ever tried uploading your django app to heroku but felt it was too complicated? If so, in this segment we will look at how you can upload your app to heroku. Don't worry, it is going to be short and to the point.

For this tutorial, I will be assuming you have an app built, so the next step you will be delving into, is on how to deploy your app to heroku.

Keeping that in mind, let's dive in and see how we can setup the app.

Prepare your app

Requirements.txt

If you are already working in a virtualenv you can easily run to create your requirements.txt file.

pip freeze > requirements.txt

If you want to manually write the version of the package just go to pypi website and find the latest version.
It should look something like this:

asgiref==3.3.4
Django==3.2.3
gunicorn==20.1.0
Pillow==8.2.0
pytz==2021.1
sqlparse==0.4.1
django-heroku==0.3.1
whitenoise==5.2.0

Procfile

Create a file with name Procfile (Make sure to not have any extension). The Procfile should be in the same directory as your manage.py file.
Install gunicorn.

pip install gunicorn

Make sure to add gunicorn to your requirements.txt file.
Add the following line to your Procfile. The app name is basically the folder name where you have your wsgi.py file.

web: gunicorn <app_name>.wsgi

settings.py

Next we will be installing a package called django-heroku, after installing make sure to add it on the requirements.txt file.

pip install django-heroku

Now go to your settings.py and import it on top.

import django_heroku

and paste this at the bottom of the file or else you are going to get a KeyError.

django_heroku.settings(locals())

Django Static

Now to setup the static assets.

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# Static files (CSS, JavaScript, Images)
# https://docs.djangoproject.com/en/1.9/howto/static-files/
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
STATIC_URL = '/static/'

This will basically tell django where to look for the static files and which folder to look for when collectstatic is run.

Install WhiteNoise and update your requirements.txt file.

pip install whitenoise

Next, install WhiteNoise into your Django application. This is done in settings.py‘s middleware section (at the top):

MIDDLEWARE_CLASSES = (
    # Simplified static file serving.
    # https://warehouse.python.org/project/whitenoise/
    'whitenoise.middleware.WhiteNoiseMiddleware',
    ...

Finally, if you would like gzip functionality enabled, also add the following setting to settings.py.

# Simplified static file serving.
# https://warehouse.python.org/project/whitenoise/

STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

We will need to create one more file called runtime.txt. This will tell heroku which version of python needs to be installed. This step is optional because heroku will use a python version automatically when building but if you want a specific python version you can add it like this.

python-3.8.5

That is it for configuring our app for deployment. Now we go to the heroku cli and see how to upload the app.

Deployment

If you don't have heroku installed on your machine follow this link

heroku login

After successful login we will be able to create our app directly from the terminal.

Create a heroku app

heroku create

This will create a heroku app with a random available name. However, if you want to give a name of your choice, just add the name after heroku create. Make sure the name is unique and available.

If you already have a heroku app and want to add the app as a Git remote, you need to execute

heroku git:remote -a <yourapp>

Now add all the files to git and commit.

git add .
git commit -m "deploy heroku"

Push all the files and build.

git push heroku master

Once done this will deploy your app. Once deployed, we will need to migrate our database.

heroku run bash

This will give us a quick terminal to control our app. Here you can run all your django commands.

python manage.py migrate

This will migrate all our files to the database.

Conclusion

That is all for now. If you have followed all the steps above you should have an app which is now running on heroku. If you have come across any issues please leave a comment or knock-me. I will try to help fix them.

Best of luck. Happy coding :D

DEV Community: Rabbil Yasar Sajal

Why .env.example Gets Out of Sync — and What Actually Fixes It

Quick answer

The problem

Why it happens

What people do about it today

The fix: a schema as the source of truth, not a description of one

The schema is not the example file

What secret = true actually does — and doesn't

Validating that the contract actually holds

The next layer: what about variables nobody declared at all?

When this approach makes sense — and when it doesn't

A practical migration path

Want to simplify how you manage your env files and secrets?

The End of .env Chaos: How a Configuration Contract Fixes Environment Variables

Read about the how EnvShield is compared to TruffleHog

EnvShield vs. TruffleHog: Configuration Contracts vs. Secret Scanning

[Boost]

EnvShield vs. TruffleHog: Configuration Contracts vs. Secret Scanning

EnvShield vs. TruffleHog: Configuration Contracts vs. Secret Scanning

TL;DR

Why this comparison keeps coming up

What each one actually does

Where they genuinely overlap

Example

Using both

Takeaway

The End of .env Chaos: How a Configuration Contract Fixes Environment Variables

env.schema.toml: the contract, not a description of one

What secret = true actually does (and doesn't)

env.schema.toml vs. .env.example

One contract, several workflows

A concrete example: catching a variable before it's committed

Deployment manifests get checked too

The takeaway

Django: Testing The What, Why and How. (Code)

Table Of Contents

Coverage

Testing Models

Test Model Implementation

Testing str

Testing Many To Many

Testing Absolute Url

Testing Views

Test View Implementation

Deny Unauthorized User

URL Is Accessed By Name

Correct Template Usage

Test num_books

Testing Forms

Next Topics To Cover

Conclusion

Django: Testing The What, Why and How (Theory).

Table Of Content

Types Of Testing

What Should Be Tested

Our Testing Project

Structure

Third Party Packages

Coverage

Django Package

Client

Testing

TestCase

How To Run A Test

Next

How To Deploy Django App To Heroku- The Simple Way

Prepare your app

Requirements.txt

Procfile

settings.py

Django Static

Deployment

Conclusion

What `secret = true` actually does — and doesn't

`env.schema.toml`: the contract, not a description of one

What `secret = true` actually does (and doesn't)

`env.schema.toml` vs. `.env.example`

Test `num_books`