Welcome to Flask’s documentation.
Get started with Installation and then get an overview with the
Quickstart. There is also a more detailed Tutorial that shows how to create a small but complete
application with Flask. Common patterns are described in the Patterns for Flask section. The rest of the
docs describe each component of Flask in detail, with a full reference in the API section.
Flask depends on the Jinja template engine and the Werkzeug WSGI toolkit. The documentation for
these libraries can be found at:
Jinja documentation
Werkzeug documentation
User’s Guide
This part of the documentation, which is mostly prose, begins with some background information about
Flask, then focuses on step-by-step instructions for web development with Flask.
Foreword
What does “micro” mean?
Configuration and Conventions
Growing with Flask
Test Coverage
Writing unit tests for your application lets you check that the code you wrote works the way you
expect. Flask provides a test client that simulates requests to the application and returns the response
data.
You should test as much of your code as possible. Code in functions only runs when the function is
called, and code in branches, such as if blocks, only runs when the condition is met. You want to
make sure that each function is tested with data that covers each branch.
The closer you get to 100% coverage, the more comfortable you can be that making a change won’t
unexpectedly change other behavior. However, 100% coverage doesn’t guarantee that your application
doesn’t have bugs. In particular, it doesn’t test how the user interacts with the application in the
browser. Despite this, test coverage is an important tool to use during development.
Note
This is being introduced late in the tutorial, but in your future projects you should test as you develop.
You’ll use pytest and coverage to test and measure your code. Install them both:
$ pip install pytest coverage
Setup and Fixtures
The test code is located in the tests directory. This directory is next to the flaskr package, not
inside it. The tests/conftest.py file contains setup functions called fixtures that each test will
use. Tests are in Python modules that start with test_, and each test function in those modules also
starts with test_.
Each test will create a new temporary database file and populate some data that will be used in the
tests. Write a SQL file to insert that data.
tests/data.sql
INSERT INTO user (username, password)
VALUES
('test',
'pbkdf2:sha256:50000$TCI4GzcX$0de171a4f4dac32e3364c7ddc7c14f3e2fa61f2d17574483f7ffb
b431b4acb2f'),
('other',
'pbkdf2:sha256:50000$kJPKsz6N$d2d4784f1b030a9761f5ccaeeaca413f27f2ecb76d6168407af96
2ddce849f79');
INSERT INTO post (title, body, author_id, created)
VALUES
('test title', 'test' || x'0a' || 'body', 1, '2018-01-01 00:00:00');
The app fixture will call the factory and pass test_config to configure the application and
database for testing instead of using your local development configuration.
tests/conftest.py
import os
import tempfile
import pytest
from flaskr import create_app
from flaskr.db import get_db, init_db
with open(os.path.join(os.path.dirname(__file__), 'data.sql'), 'rb') as f:
_data_sql = f.read().decode('utf8')
@pytest.fixture
def app():
db_fd, db_path = tempfile.mkstemp()
app = create_app({
'TESTING': True,
'DATABASE': db_path,
})
with app.app_context():
init_db()
get_db().executescript(_data_sql)
yield app
os.close(db_fd)
os.unlink(db_path)
@pytest.fixture
def client(app):
return app.test_client()
@pytest.fixture
def runner(app):
return app.test_cli_runner()
tempfile.mkstemp() creates and opens a temporary file, returning the file object and the path to
it. The DATABASE path is overridden so it points to this temporary path instead of the instance folder.
After setting the path, the database tables are created and the test data is inserted. After the test is over,
the temporary file is closed and removed.
TESTING tells Flask that the app is in test mode. Flask changes some internal behavior so it’s easier to
test, and other extensions can also use the flag to make testing them easier.
The client fixture calls app.test_client() with the application object created by the app
fixture. Tests will use the client to make requests to the application without running the server.
The runner fixture is similar to client. app.test_cli_runner() creates a runner that can
call the Click commands registered with the application.
Pytest uses fixtures by matching their function names with the names of arguments in the test
functions. For example, the test_hello function you’ll write next takes a client argument. Pytest
matches that with the client fixture function, calls it, and passes the returned value to the test
function.
