Developer Guides

Flagsmith API

Local development

The project assumes the following tools installed:

• Python. Any version allowed by requires-python in pyproject.toml is supported.
• GNU Make.
• Docker or a compatible tool like Podman. We recommend OrbStack for macOS.

To install dev dependencies, run make install.

To run linters, run make lint.

To run tests, run make docker-up test.

To prepare a dev database, run make docker-up django-migrate.

To bring up a dev server, run make serve, or make serve-with-task-processor to run the Task processor alongside the server.

Code guidelines: testing

The required diff test coverage for our backend PRs is 100%. This policy gives us more confidence to ship, helps us to find bugs earlier, and promotes the test-driven development (TDD) approach. We encourage you to add new tests, and modify existing ones, ahead of writing the code.

This codebase includes two kinds of tests:

• Black box API tests in tests/integration directory. Ideally, these are intended to only invoke API endpoints, and verify their output.
• Tests for individual modules, classes and functions in tests/unit directory.

We avoid class-based tests. To manage test lifecycle and dependencies, we rely on Pytest features such as fixtures, markers, parametrisation, and hooks. Read conftest.py for commonly used fixtures.

We recommend naming test functions using the test_{subject}__{condition}__{expected outcome} template, e.g. test_get_version__valid_file_contents__returns_version_number.

We use the Given When Then structure in all our tests.

Code guidelines: migrations

To auto-generate migrations for your new code, run make docker-up django-make-migrations.

The prompt will ask you for a name and not generate one; we avoid auto-generated migration names.

Squash newly added migrations whenever you can.

Code guidelines: typing

This codebase, including tests, is fully type-checked by Mypy in strict mode. Resolving existing # type: ignore comments is always welcome. If you happen to bring a new # type: ignore comment, please document the reason, and consider fixing a small number of adjacent # type: ignore comments, if possible and appropriate for the scope of your task.

To run a full type check, run make typecheck.

Code guidelines: design and architecture

Core API consists of Django apps with usual Django submodules like:

• apps.py
• middleware.py
• models.py
• serializers.py
• views.py
• urls.py

We tend to add our own layers in the following modules:

• constants.py for app-wide constant variables.
• dataclasses.py for dataclass definitions, typically used for internal data transfer objects (DTOs).
• mappers.py for data mapping logic unrelated to API requests and responses.
• services.py for encapsulated business logic. Our goal with this layer is to make the views, models and serialisers leaner, so that the business logic is more clearly defined and easier to compose.
• tasks.py for defining asynchronous and recurring tasks.
• types.py for custom type definitions, including typed dicts.

Code guidelines: Flagsmith on Flagsmith

To gate and gradually rollout features in the backend, we use the Flagsmith SDK in local evaluation mode:

from integrations.flagsmith.client import get_client

flagsmith_client = get_client("local", local_eval=True)
flags = flagsmith_client.get_identity_flags(
    organisation.flagsmith_identifier,
    traits=organisation.flagsmith_on_flagsmith_api_traits,
)
ai_enabled = flags.is_feature_enabled("ai")

To modify or add flags, edit integrations/flagsmith/data/environment.json, or run poetry run python manage.py updateflagsmithenvironment.

Flagsmith Frontend

Development

npm install
npm run dev

E2E Testing

E2E tests use Playwright with Firefox and include videos, traces, and HTML reports for debugging.

Prerequisites

1. Docker running with Flagsmith services: docker compose up -d
2. Environment variables in docker-compose.yml:

   E2E_TEST_AUTH_TOKEN: 'some-token'
   ENABLE_FE_E2E: 'true'

3. Matching token in frontend/.env:

   E2E_TEST_TOKEN_DEV=some-token

Running Tests

# Run all tests
npm run test

# Run with Playwright UI (for debugging)
npm run test:dev

# Run specific test file
npm run test -- tests/flag-tests.pw.ts

# Run only OSS tests
npm run test -- --grep-invert @enterprise

# Run only Enterprise tests
npm run test -- --grep @enterprise

Environment Variables

Variable	Description
SKIP_BUNDLE=1	Skip webpack build for faster iteration
E2E_CONCURRENCY=N	Number of parallel workers (default: 20, use 1 for debugging)
E2E_RETRIES=0	Fail-fast mode - stop on first failure
E2E_REPEAT=N	Run tests N additional times after passing to detect flakiness

Examples

# Fast iteration (skip bundle, fail on first error)
E2E_RETRIES=0 SKIP_BUNDLE=1 npm run test -- tests/flag-tests.pw.ts

# Check for flaky tests (run 5 extra times after passing)
E2E_REPEAT=5 npm run test -- tests/flag-tests.pw.ts

# Debug with low concurrency
E2E_RETRIES=0 SKIP_BUNDLE=1 E2E_CONCURRENCY=1 npm run test -- tests/flag-tests.pw.ts

Test Results

• HTML Report: e2e/playwright-report/ - Interactive dashboard with search/filter
• Test Artifacts: e2e/test-results/ - Contains for each failed test:
  • error-context.md - DOM snapshot at failure point
  • trace.zip - Interactive trace viewer
  • Screenshots and videos

Claude Code Commands

When using Claude Code, these commands are available for e2e testing:

• /e2e [N] - Run all tests (OSS + Enterprise), auto-fix failures, re-run until passing
• /e2e-oss [N] - Run OSS tests only, auto-fix failures, re-run until passing
• /e2e-ee [N] - Run Enterprise tests only, auto-fix failures, re-run until passing
• /e2e-create [description] - Create a new test following existing patterns

The optional [N] argument sets E2E_REPEAT to run tests N additional times after passing (defaults to 0). E.g., /e2e 5 runs tests, then repeats 5 more times to detect flakiness.

Documentation

docs.flagsmith.com is built using Docusaurus 2, a modern static website generator.

Installation

npm install

Local Development

make serve

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

When forwarding port 3000 from a remote server or VM, you can run the dev server on 0.0.0.0 to make it listen on the local IP.

npm run start -- --host 0.0.0.0

Checking your changes with prettier

After you make changes to the documentation, you can check the changes by running the following command:

make lint

If you want to apply any fixes discovered, you can run the following command:

npx prettier <YOUR_DOC> --write

OpenAPI generator

We are using the https://github.com/PaloAltoNetworks/docusaurus-openapi-docs plugin to generate the OpenAPI docs. The source schema is located in sdk/openapi.yaml.

To regenerate the docs, run:

make generate-sdk-api-docs

Build

npm run build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

This site is set to auto deploy to Vercel.