{"id":316,"date":"2026-11-18T12:00:00","date_gmt":"2026-11-18T12:00:00","guid":{"rendered":"https:\/\/rezachegini.com\/?p=316"},"modified":"2026-11-18T19:19:59","modified_gmt":"2026-11-18T19:19:59","slug":"building-a-job-board-api-part-21-100-coverage-and-why-the-gate-is-80","status":"publish","type":"post","link":"https:\/\/rezachegini.com\/?p=316","title":{"rendered":"Building a Job Board API, Part 21: 100% Coverage, and Why the Gate Is 80"},"content":{"rendered":"<p>I&#8217;m sharing one of my projects here from the beginning, step by step. It&#8217;s a Job Board API built with Django, Django REST Framework, PostgreSQL and Docker Compose, with S3 and SQS (through LocalStack), Redis, and a background worker.<\/p>\n<p>I&#8217;m a junior engineer looking for my first role in DevOps, SRE or Cloud. That&#8217;s why I build projects like this and write about them in public. It shows how I think, and writing it down helps me really understand it.<\/p>\n<p>This is the last article about the tests. At the end of Part 20, the suite had 178 tests and 99% coverage. A few lines were still never run:<\/p>\n<ul class=\"wp-block-list\">\n<li>views.py lines 77 and 126, and line 124;<\/li>\n<li>filters.py line 17;<\/li>\n<li>settings.py line 16;<\/li>\n<li>the last two lines of worker\/run_worker.py.<\/li>\n<\/ul>\n<p>At 99%, the job wasn&#8217;t &#8220;reach 100%&#8221;. It was to decide about each remaining line, honestly, and then make the target enforced. Each line got one of three decisions:<\/p>\n<ul class=\"wp-block-list\">\n<li>Delete it, because the code can never run.<\/li>\n<li>Test it, because a test can reach it.<\/li>\n<li>Exclude it, with one narrow, named rule.<\/li>\n<\/ul>\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" decoding=\"async\" src=\"http:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-21-diagram.png\" alt=\"Every missed line gets a decision, not a test written just to cover it\" class=\"wp-image-315\" width=\"744\" height=\"329\" srcset=\"https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-21-diagram.png 744w, https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-21-diagram-300x133.png 300w\" sizes=\"auto, (max-width: 744px) 100vw, 744px\" \/><\/figure>\n<p>The result: 194 passed, 100% coverage (670 of 670 lines), and exit code 0. But the 100% isn&#8217;t the point. The point is that no line was left undecided.<\/p>\n<h3 class=\"wp-block-heading\">Decision 1: delete the code that can never run<\/h3>\n<p>Back in Part 19, coverage marked two lines in views.py as never run. They were role checks inside perform_create. Before:<\/p>\n<pre class=\"wp-block-code\"><code>def perform_create(self, serializer):\n        if not self.request.user.is_company:\n            raise PermissionDenied(\"Only company users can create jobs.\")\n        serializer.save(company=self.request.user.company)<\/code><\/pre>\n<p>After:<\/p>\n<pre class=\"wp-block-code\"><code>def perform_create(self, serializer):\n        serializer.save(company=self.request.user.company)<\/code><\/pre>\n<p>Why could the check never run? For create, get_permissions() returns [IsAuthenticated(), IsVerifiedCompany()]. DRF runs those before the view method. A non-company user is rejected with 403 there, so perform_create only ever sees company users. The permission matrix in Part 19 proves this for every role.<\/p>\n<p>Why delete it instead of keeping it as &#8220;defence in depth&#8221;?<\/p>\n<ul class=\"wp-block-list\">\n<li>A check that can&#8217;t run protects nothing.<\/li>\n<li>It repeats the rule in a second place, with different wording: &#8220;Only company users can create jobs.&#8221; against &#8220;Only company accounts can do this.&#8221;<\/li>\n<li>If someone removed the permission class one day, users would get a message that no test covers. And the permission matrix would already fail loudly.<\/li>\n<\/ul>\n<p>So: one rule, in one place, guarded by tests.<\/p>\n<p>The same for applications. IsCandidate already guarantees the user is a candidate and has a candidate_profile, so the extra check went too. The race fallback in that method stayed, because it can run, and Part 20 tests it.<\/p>\n<p>PermissionDenied was no longer used, so I removed it from the import as well. Unused imports are noise, and linters flag them. grep -c &#8220;PermissionDenied&#8221; jobs\/views.py now returns 0.<\/p>\n<p>Proven safe: after deleting both checks, all 42 permission tests still passed. That&#8217;s the proof they were unreachable.<\/p>\n<h3 class=\"wp-block-heading\">Decision 2: test the lines a test can reach<\/h3>\n<h3 class=\"wp-block-heading\">OPTIONS: the only request that reaches the fallback<\/h3>\n<pre class=\"wp-block-code\"><code>@pytest.mark.parametrize((\"who\", \"expected\"), [(\"anon\", 401), (\"sam\", 200), (\"acme\", 200)])\ndef test_options_needs_a_login(client_for, who, expected):\n    assert client_for(who).options(\"\/api\/applications\/\").status_code == expected<\/code><\/pre>\n<p>This covers views.py line 124: return super().get_permissions() at the end of ApplicationViewSet.get_permissions(). Every named action (create, retrieve, resume, set_status) returns earlier. So which request ever reaches the last line?<\/p>\n<p>OPTIONS. DRF handles it as the metadata action: it describes the endpoint&#8217;s fields. The fallback applies the global default, IsAuthenticated.<\/p>\n<p>What it proves: anonymous users can&#8217;t use OPTIONS to read the API&#8217;s field list (401), and logged-in users of either role can (200). This is a good example of coverage pointing at a real question: who is allowed to ask the API to describe itself?<\/p>\n<h3 class=\"wp-block-heading\">The empty skills filter<\/h3>\n<pre class=\"wp-block-code\"><code>def test_skills_filter_with_only_commas_returns_everything(api_as, board):\n    response = api_as(board.user).get(\"\/api\/jobs\/\", {\"skills\": \" , ,\"})\n\n    assert sorted(titles(response)) == [\"Data Analyst\", \"Junior DevOps Engineer\", \"SRE Intern\"]<\/code><\/pre>\n<p>This covers filters.py line 17. After normalising, &#8221; , ,&#8221; is an empty list, so the filter returns the jobs unfiltered. Why does that matter? An empty list passed to the database&#8217;s array overlap would match nothing. That&#8217;s the opposite of what &#8220;no skills given&#8221; means. The expected result is all three open jobs, and the closed one stays hidden.<\/p>\n<h3 class=\"wp-block-heading\">The env() helpers from Part 16<\/h3>\n<p>This covers settings.py line 16, the raise in env(). The tests live in a new config\/tests\/test_settings.py, and use a variable name that nothing else uses:<\/p>\n<pre class=\"wp-block-code\"><code>NAME = \"JOBBOARD_TEST_SETTING\"\n\n\n@pytest.mark.parametrize(\"value\", [None, \"\"])\ndef test_required_setting_missing_or_empty_raises(monkeypatch, value):\n    if value is None:\n        monkeypatch.delenv(NAME, raising=False)\n    else:\n        monkeypatch.setenv(NAME, value)\n\n    with pytest.raises(ImproperlyConfigured, match=f\"Missing required environment variable: {NAME}\"):\n        env(NAME)<\/code><\/pre>\n<p>The other helper tests:<\/p>\n<ul class=\"wp-block-list\">\n<li>The fail-fast rule from Part 16: missing and empty both count as missing.<\/li>\n<li>monkeypatch.delenv and setenv change the process environment for this test only. raising=False means &#8220;don&#8217;t complain if it&#8217;s already absent&#8221;.<\/li>\n<li>Why test the helper, and not &#8220;the settings fail at startup&#8221;? Settings are imported once per process, so changing an environment variable can&#8217;t re-run settings.py inside a test. The real startup failure was proven in Part 16, by running the image with no environment. These tests lock in the rules the helper applies.<\/li>\n<\/ul>\n<p>An optional setting: unset gives the default, empty gives the default (the same rule as required), and set gives the value.<\/p>\n<p>env_bool: &#8220;1&#8221;, &#8220;true&#8221;, &#8221; Yes &#8221; and &#8220;on&#8221; are True. &#8220;False&#8221; and &#8220;0&#8221; are False. And &#8220;ture&#8221;, a typo, is False, so a typo in DJANGO_DEBUG can never switch debug mode on. The test uses is expected, so the result must be a real bool, not just something truthy.<\/p>\n<p>env_list with deliberately messy input, the kind that ends up in a hand-edited .env:<\/p>\n<pre class=\"wp-block-code\"><code> monkeypatch.setenv(NAME, \" localhost, 127.0.0.1 ,,10.0.0.149 ,\")\n    assert env_list(NAME) == [\"localhost\", \"127.0.0.1\", \"10.0.0.149\"]<\/code><\/pre>\n<p>Spaces around items, a doubled comma, and a trailing comma. The empty pieces are dropped. It&#8217;s the real shape of my DJANGO_ALLOWED_HOSTS, with thor&#8217;s LAN IP.<\/p>\n<h3 class=\"wp-block-heading\">Decision 3: exclude, with one narrow, named rule<\/h3>\n<p>The last two lines of worker\/run_worker.py:<\/p>\n<pre class=\"wp-block-code\"><code>if __name__ == \"__main__\":\n    main()<\/code><\/pre>\n<p>These only run when the file is started as a script (python -m worker.run_worker), never when a test imports it. And main() itself is fully tested, with the fake queue from Part 20. So there&#8217;s nothing left to test here.<\/p>\n<pre class=\"wp-block-code\"><code>[tool.coverage.report]\nexclude_also = ['if __name__ == .__main__.:']<\/code><\/pre>\n<p>exclude_also adds to coverage.py&#8217;s built-in exclusions, instead of replacing them.<\/p>\n<p>It&#8217;s a regular expression. Each . matches any one character, so it matches both &#8220;__main__&#8221; and &#8216;__main__&#8217;.<\/p>\n<p>The TOML string uses single quotes, so the pattern can contain double quotes freely.<\/p>\n<p>When a line is excluded, the block under it is excluded too, so the main() call on the next line goes with it.<\/p>\n<p>Why this, and not # pragma: no cover? A pragma is a comment you put on a line to hide it from coverage. One named rule for a well-known, untestable pattern is honest. Pragmas sprinkled on code that&#8217;s merely hard to test hide real gaps. This is the only exclusion rule in the project.<\/p>\n<h3 class=\"wp-block-heading\">The gate: 80%, while the suite is at 100%<\/h3>\n<pre class=\"wp-block-code\"><code>[tool.pytest.ini_options]\nDJANGO_SETTINGS_MODULE = \"config.settings\"\npython_files = [\"test_*.py\"]\naddopts = \"--cov --cov-report=term-missing --cov-fail-under=80\"<\/code><\/pre>\n<p>&#8211;cov-fail-under=80: after the tests, pytest-cov compares the total coverage with 80. Below that, it prints FAIL Required test coverage of 80% not reached and the run exits with a non-zero code.<\/p>\n<p>That means a run can fail with every test passing. Green tests aren&#8217;t enough anymore.<\/p>\n<p>I proved it with the two smoke tests from Part 18, run alone with coverage:<\/p>\n<pre class=\"wp-block-code\"><code>2 passed\nFAIL Required test coverage of 80% not reached. Total coverage: 58.66%\nexit code: 1<\/code><\/pre>\n<p>And the full suite:<\/p>\n<pre class=\"wp-block-code\"><code>exit code: 0\nTOTAL 670 0 100%\nRequired test coverage of 80% reached. Total coverage: 100.00%\n194 passed<\/code><\/pre>\n<p>Why 80 and not 100?<\/p>\n<ul class=\"wp-block-list\">\n<li>80 is the target in my project&#8217;s spec.<\/li>\n<li>The gate catches a real drop, like a new module with no tests, without failing the build over one uncovered line in an error handler.<\/li>\n<li>A 100% hard gate pushes people the wrong way. They start writing tests just to cover lines, or excluding awkward code to make the number. That&#8217;s exactly what the three decisions above avoid.<\/li>\n<\/ul>\n<p>The exit code is what CI will use in my next project: non-zero blocks the merge. For quick, focused runs, &#8211;no-cov turns off coverage and the gate together.<\/p>\n<h3 class=\"wp-block-heading\">The $? trap<\/h3>\n<p>The obvious way to check the exit code is something like docker compose run &#8211;rm test | tail -n 4; echo $?. That&#8217;s wrong. After a pipe, $? is the exit code of the last command, tail, which is always 0. A failing test run would look like a success.<\/p>\n<p>The right way is to redirect to a file first:<\/p>\n<pre class=\"wp-block-code\"><code>docker compose run --rm test &gt; \/tmp\/pytest.out 2&gt;&amp;1; echo \"exit code: $?\"; tail -n 4 \/tmp\/pytest.out<\/code><\/pre>\n<p>Now $? is pytest&#8217;s own exit code, and tail reads the file afterwards. This matters in any shell script or CI step: a pipe can quietly swallow a failure.<\/p>\n<h3 class=\"wp-block-heading\">How I know my tests actually work<\/h3>\n<p>100% coverage only says every line ran during the tests. It doesn&#8217;t say the tests would notice if a line were wrong. A test with no useful assert still &#8220;covers&#8221; lines.<\/p>\n<p>That&#8217;s why, in every group of tests in Phase 5, I broke the code on purpose and checked which tests failed. Here is every deliberate bug in one place:<\/p>\n<ol class=\"wp-block-list\">\n<li>The match score (Part 18). if not required: became if required is None:. Exactly 2 tests failed, the two &#8220;no skills&#8221; cases, with ZeroDivisionError.<\/li>\n<li>The owner check (Part 19). IsJobOwner was removed from the views. 7 failed, 35 passed. The 7 were exactly the non-owner cases of job update, applicants and status change, and the output showed non-owners had really changed Acme&#8217;s job.<\/li>\n<li>Skill normalising (Part 19). .lower() was removed. Exactly 2 failed, the two normalisation tests.<\/li>\n<li>Publishing after commit (Part 20). transaction.on_commit(send) became send(). Exactly 2 failed: &#8220;published only after commit&#8221; and &#8220;rolled back publishes nothing&#8221;.<\/li>\n<li>Cache invalidation after commit (Part 20). transaction.on_commit(bump) became bump(). Exactly 1 failed: the &#8220;invalidates only after commit&#8221; test.<\/li>\n<\/ol>\n<p>And two checks in the opposite direction, in this part:<\/p>\n<ol class=\"wp-block-list\">\n<li>Deleting the dead role checks. All 42 permission tests still passed. If removing code breaks nothing, and the tests cover that path, the code really was unreachable.<\/li>\n<li>The gate itself. The two smoke tests alone: 2 passed, and still exit code 1. The gate fails a run whose tests all pass.<\/li>\n<\/ol>\n<p>The pattern in every case: the failures pointed straight at the bug, and nothing unrelated failed. That&#8217;s what tells me the tests are aimed at the right things, not just running lines. After each check, git checkout restored the code, and everything passed again.<\/p>\n<p>This was manual mutation testing. There are tools that do it automatically, by making hundreds of small changes and counting how many the tests catch. Doing it by hand, one change at a time, taught me what a good test failure looks like.<\/p>\n<h3 class=\"wp-block-heading\">Problems I hit<\/h3>\n<h3 class=\"wp-block-heading\">1. addopts: command not found<\/h3>\n<p>I pasted the TOML line addopts = &#8220;&#8230;&#8221; into the shell. It&#8217;s a line for pyproject.toml, not a command. I fixed it properly: sed to change the existing addopts line, and a guarded cat &gt;&gt; pyproject.toml &lt;&lt;&#8216;EOF&#8217; for the new [tool.coverage.report] section. Then I checked the file was still valid TOML:<\/p>\n<pre class=\"wp-block-code\"><code>python3 -c \"import tomllib; ...\"<\/code><\/pre>\n<p>It printed toml OK.<\/p>\n<h3 class=\"wp-block-heading\">2. The same 178 tests and 3 missed lines<\/h3>\n<p>The first runs after my changes still showed 178 passed and the same 3 missed lines (settings.py 16, filters.py 17, views.py 124). The new tests hadn&#8217;t actually been added to the files yet. The unchanged test count was the clue. I added them with cat &gt;&gt; and cat &gt; heredocs, and the run went to 194 and 100%.<\/p>\n<h3 class=\"wp-block-heading\">3. My expected counts were off again<\/h3>\n<p>I expected 193 tests and 12 job-test functions. The real numbers were 194 (the settings file has 12 cases, not 11) and 11 functions. Same lesson as Part 20: read the real output.<\/p>\n<h3 class=\"wp-block-heading\">What I learned<\/h3>\n<ul class=\"wp-block-list\">\n<li>Coverage is a gate, not a number. &#8211;cov-fail-under turns it into an exit code that CI can act on.<\/li>\n<li>A run can fail with every test passing.<\/li>\n<li>Decide about each missed line: delete it, test it, or exclude it with a named rule.<\/li>\n<li>Dead code is not defence in depth. If tests guard the real rule, a second, unreachable copy only adds a second message that nothing tests.<\/li>\n<li>A narrow, named exclusion is honest. Scattered pragmas hide gaps.<\/li>\n<li>OPTIONS reaches the fallback permission path in a DRF viewset.<\/li>\n<li>Test configuration helpers with monkeypatch.setenv and delenv, not by re-importing settings.<\/li>\n<li>After a pipe, $? belongs to the last command.<\/li>\n<li>100% coverage says lines ran. Breaking the code on purpose says the tests would notice.<\/li>\n<\/ul>\n<h3 class=\"wp-block-heading\">The testing series in one paragraph<\/h3>\n<p>Over four articles, the Job Board API went from zero automated tests to 194. They run in a container with one command, docker compose run &#8211;rm test, against a throwaway PostgreSQL database, with Redis, S3, SQS and email replaced inside the test process. They cover the permission matrix, every endpoint, the worker&#8217;s loop and its failure paths, and two known gaps are documented in tests instead of hidden. Coverage is 100%, the gate is 80%, and every group of tests was proven by breaking the code on purpose.<\/p>\n<p>This completes the first item of Phase 5, &#8220;pytest with 80%+ coverage, including permission tests&#8221;. And it gives the phase&#8217;s goal its command: docker compose run &#8211;rm test runs the full suite green and reports coverage.<\/p>\n<h3 class=\"wp-block-heading\">What comes next<\/h3>\n<p>The exit code from this gate is exactly what a CI pipeline needs. In my next project, a pipeline will run this same command on every change, and a non-zero exit code will block the merge. Before that, the rest of Phase 5 continues, and I&#8217;ll keep writing it up here.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>I&#8217;m sharing one of my projects here from the beginning, step by step. It&#8217;s a Job Board API built with Django, Django&hellip;<\/p>\n","protected":false},"author":2,"featured_media":314,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_rezaops_part":"21","_rezaops_linkedin_url":"https:\/\/www.linkedin.com\/pulse\/building-job-board-api-part-21-100-coverage-why-gate-80-reza-chegini-tmyrc\/","footnotes":""},"categories":[10,116],"tags":[214,8,111,191,118,212,25,112,213],"series":[117],"class_list":["post-316","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops","category-django","tag-coverage","tag-devops","tag-django","tag-drf","tag-job-board","tag-pytest","tag-python","tag-rest-api","tag-testing","series-job-board-api"],"jetpack_featured_media_url":"https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-21-cover.png","_links":{"self":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts\/316","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=316"}],"version-history":[{"count":1,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts\/316\/revisions"}],"predecessor-version":[{"id":317,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts\/316\/revisions\/317"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/media\/314"}],"wp:attachment":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=316"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=316"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=316"},{"taxonomy":"series","embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fseries&post=316"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}