DEV Community: DuneDev

How to Monitor Nginx Logs with Grafana, Loki & Promtail on Docker

DuneDev — Sun, 15 Sep 2024 16:53:33 +0000

Introduction

We will follow the flow of the Nginx logs data until it is displayed in Grafana. To begin with, in this case, we will need a custom/structured Nginx access log format. This way, we can access the data in Grafana more intuitively and in a more organized manner.

Nginx config

For this, we will need an nginx.conf with a configuration similar to this one, where we specify the structure of the access log using the log_format directive. This is necessary for the Grafana template that we are going to use to visualize the data.

# nginx.conf

user  myapp;

error_log  /var/log/myapp/error.log warn;
pid        /var/run/myapp.pid;

events {
  worker_connections  1024;
}

http {
    log_format json_analytics escape=json '{'

                            '"msec": "$msec", ' # request unixtime in seconds with a milliseconds resolution

                            '"connection": "$connection", ' # connection serial number

                            '"connection_requests": "$connection_requests", ' # number of requests made in connection

                    '"pid": "$pid", ' # process pid

                    '"request_id": "$request_id", ' # the unique request id

                    '"request_length": "$request_length", ' # request length (including headers and body)

                    '"remote_addr": "$remote_addr", ' # client IP

                    '"remote_user": "$remote_user", ' # client HTTP username

                    '"remote_port": "$remote_port", ' # client port

                    '"time_local": "$time_local", '

                    '"time_iso8601": "$time_iso8601", ' # local time in the ISO 8601 standard format

                    '"request": "$request", ' # full path no arguments if the request

                    '"request_uri": "$request_uri", ' # full path and arguments if the request

                    '"args": "$args", ' # args

                    '"status": "$status", ' # response status code

                    '"body_bytes_sent": "$body_bytes_sent", ' # the number of body bytes exclude headers sent to a client

                    '"bytes_sent": "$bytes_sent", ' # the number of bytes sent to a client

                    '"http_referer": "$http_referer", ' # HTTP referer

                    '"http_user_agent": "$http_user_agent", ' # user agent

                    '"http_x_forwarded_for": "$http_x_forwarded_for", ' # http_x_forwarded_for

                    '"http_host": "$http_host", ' # the request Host: header

                    '"server_name": "$server_name", ' # the name of the vhost serving the request

                    '"request_time": "$request_time", ' # request processing time in seconds with msec resolution

                    '"upstream": "$upstream_addr", ' # upstream backend server for proxied requests

                    '"upstream_connect_time": "$upstream_connect_time", ' # upstream handshake time incl. TLS

                    '"upstream_header_time": "$upstream_header_time", ' # time spent receiving upstream headers

                    '"upstream_response_time": "$upstream_response_time", ' # time spent receiving upstream body

                    '"upstream_response_length": "$upstream_response_length", ' # upstream response length

                    '"upstream_cache_status": "$upstream_cache_status", ' # cache HIT/MISS where applicable

                    '"ssl_protocol": "$ssl_protocol", ' # TLS protocol

                    '"ssl_cipher": "$ssl_cipher", ' # TLS cipher

                    '"scheme": "$scheme", ' # http or https

                    '"request_method": "$request_method", ' # request method

                    '"server_protocol": "$server_protocol", ' # request protocol, like HTTP/1.1 or HTTP/2.0

                    '"pipe": "$pipe", ' # "p" if request was pipelined, "." otherwise

                    '"gzip_ratio": "$gzip_ratio", '

                    '"http_cf_ray": "$http_cf_ray",'

                    '}';
    access_log /var/log/myapp/json_access.log json_analytics;

    server {
        listen 80;

        location / {
            add_header 'Access-Control-Allow-Origin' '*';
            add_header 'Access-Control-Allow-Credentials' 'true';
            add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
            add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
        }
    }
}

To begin, we need to make sure that the logs of our Nginx container are persistent in a volume. For this, we specify in the docker-compose.yaml file that we will link the .logs/ directory on our host machine to the /var/log/nginx directory. Let’s assume that this docker-compose.yml file is located in the ./myapp directory. This way, we separate the application containers from the monitoring containers.

# docker-compose.yml (myapp)

version: "3.8"
services:

    #… Rest of your services

    nginx:
    image: nginx
    restart: always
    ports:
      - "8082:80"
    networks:
      - app-network
    volumes:
      - ./logs:/var/log/nginx

networks:
  app-network:
    driver: bridge

Monitoring docker-compose.yml

Next, we will create a docker-compose.yml file in which we will specify the containers needed for monitoring the logs of the Nginx container.

In this case, these will be: Promtail, Loki, and Grafana. We will create this in the ./monitoring directory (at the same level as the myapp directory). The file will look like this:

# docker-compose.yml (monitoring)

version: "3.8"

services:

  grafana:
    image: grafana/grafana-oss
    container_name: grafana
    restart: unless-stopped
    ports:
      - '4000:3000'
    volumes:
      - grafana_data:/var/lib/grafana

  loki:
    image: grafana/loki:3.0.1
    container_name: grafana-loki
    user: "0" # To force the container to use root user and avoid permission problems
    command: -config.file=/etc/loki/local-config.yaml
    volumes:
      - ./loki-config.yaml:/etc/loki/local-config.yaml
      - ./loki_data:/loki
    restart: unless-stopped
    ports:
      - "3100:3100"

  promtail:
    image: grafana/promtail:2.9.0
    container_name: promtail
    volumes:
      - ../myapp/logs:/var/log/nginx_myapp # Here we tell Promtail where the logs are
      # In case more app logs are needed
      # - ../app_name/logs:/var/log/nginx_app_name
      - ./promtail-config.yaml:/etc/promtail/config.yml
    command: -config.file=/etc/promtail/config.yml
    restart: unless-stopped

volumes:
  grafana_data: {}

networks:
  grafana:

Promtail config

Now we need to configure both Promtail and Loki. Starting with Promtail, we need to create a file called promtail-config.yaml where we will specify its behavior (this file should be located in the "monitoring" directory):

#promtail-config.yaml

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  # myapp Config
  - job_name: nginx_myapp
    static_configs:
      - targets:
          - localhost
        labels:
          job: nginx_myapp
          __path__: /var/log/nginx_myapp/*log
    pipeline_stages:
      - json:
          expressions:
            timestamp: time_iso8601
      - timestamp:
          source: timestamp
          format: RFC3339
          action_on_failure: 'skip'

# In case more apps need to be added
#  - job_name: nginx_app-name
#    static_configs:
#      - targets:
#          - localhost
#        labels:
#          job: nginx_app-name
#          __path__: /var/log/nginx_app-name/*log
#
#    pipeline_stages:
#      - json:
#          expressions:
#            timestamp: time_iso8601
#      - timestamp:
#          source: timestamp
#          format: RFC3339
#          action_on_failure: 'skip'

Note: It’s important to highlight that the value of the job_name/labels → job property will be the one displayed in Grafana.

Loki config

Next, we move on to configuring Loki. To do this, within the "monitoring" directory, we need to create ./loki_data/, where Loki’s data will persist, because we will specify in its configuration file called loki-config.yaml (which must be located in the "monitoring" directory) that the data should persist on the local system. In this case, only data less than 7 days old (168h) should persist.

#loki-config.yaml

auth_enabled: false

server:
  http_listen_port: 3100
  grpc_listen_port: 9096

common:
  path_prefix: /loki
  ring:
    kvstore:
      store: memberlist
  replication_factor: 1

schema_config:
  configs:
    - from: "2024-01-01"
      index:
        period: 24h
        prefix: index_
      object_store: filesystem
      schema: v13
      store: tsdb

storage_config:
  tsdb_shipper:
    active_index_directory: /loki/tsdb-index
    cache_location: /loki/tsdb-cache
    cache_ttl: 168h

ingester:
  wal:
    enabled: true
    dir: /loki/wal

query_scheduler:
  max_outstanding_requests_per_tenant: 32768

querier:
  max_concurrent: 16

analytics:
  reporting_enabled: false

memberlist:
  join_members:
    - "127.0.0.1"
  abort_if_cluster_join_fails: false

limits_config:
  retention_period: 168h
  reject_old_samples: true
  reject_old_samples_max_age: 168h
  max_cache_freshness_per_query: 1m

Finally

Once we have all this set up, we just need to test by starting up the app containers by navigating to the "myapp" directory and running:

sudo docker-compose up -d

Then we move to the "monitoring" directory and run the same command to start the monitoring containers.

To access Grafana, we only need to use our browser and specify the server's IP and, in this case, port 4000 (which we specified in the docker-compose.yml file in the monitoring directory):

http://server_ip:4000/

Note: The default username and password for the first Grafana login are admin.

Once we are inside Grafana, we need to go to the Connections > Data sources section and add Loki as a data source, specifying the path to our Loki container (http://loki:3100)

Now that we have our data source added, we can go to the Dashboards section and create one for our app.

As a final tip, I recommend using the Grafana dashboard for log monitoring from this link: https://grafana.com/grafana/dashboards/12559-loki-nginx-service-mesh-json-version/. By accessing this link, we can copy the dashboard ID and import it from the Grafana web portal that we have deployed.

React Suspense for data fetching

DuneDev — Mon, 02 Sep 2024 17:28:43 +0000

Suspense For Data Fetching

Since React 18, Suspense has improved not only by supporting asynchronous component loading but also by allowing asynchronous data loading and handling within a component. This way, we can avoid using state and useEffect to control asynchronous data within a component.

In this post, we will explore how we can improve the readability of our code by using Suspense for asynchronous data control within the component, along with ErrorBoundaries to handle errors in these asynchronous calls.

Let’s start by understanding the ErrorBoundary component (in this case, it’s a component I defined, but you can use libraries that already implement it), which will encapsulate our components that depend on asynchronous data, waiting to catch any rendering errors in the component. If an error is detected, it will handle it by displaying a fallback component.

// ErrorBoundary.tsx
import React, { ErrorInfo, ReactNode } from "react";

interface ErrorBoundaryProps {
  fallback: ReactNode;
  children: ReactNode;
}

class ErrorBoundary extends React.Component<ErrorBoundaryProps> {
  state = { hasError: false };

  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  static getDerivedStateFromError(error: Error) {
    return { hasError: true };
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    console.log(error, info);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

export default ErrorBoundary;

First, I will show how our App.tsx and Pokemon.tsx components would look without using Suspense.

// App.tsx
import "./App.css";
import ErrorBoundary from "./ErrorBoundary";
import Pokemon from "./Pokemon";

function App() {
  return (
    <>
      <ErrorBoundary fallback="There was an error. Ups... :p">
        <Pokemon name="charmander" />
      </ErrorBoundary>
      <ErrorBoundary fallback="There was an error. Ups... :p">
        <Pokemon name="asda" />
      </ErrorBoundary>
    </>
  );
}

export default App;

// Pokemon.tsx
import { useEffect, useState } from 'react';

interface PokemonProps {
    name: string;
}

function Pokemon({ name }: PokemonProps) {
  const [data, setData] = useState<Pokemon | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  interface Pokemon {
    name: string;
    height: string;
  }

  useEffect(() => {
    fetch(`https://pokeapi.co/api/v2/pokemon/${name}`)
      .then((response) => {
        if (!response.ok) {
          throw new Error('Network response was not ok');
        }
        return response.json();
      })
      .then((data: Pokemon) => {
        setData(data);
        setLoading(false);
      })
      .catch((error: Error) => {
        setError(error);
        setLoading(false);
      });
  }, []);

  if (loading) {
    return <div>Loading...</div>;
  }

  if (error) {
    // Throw here to force a render error so ErrorBoundary can catch it.
    throw error; // Throw error to ErrorBoundary
  }

  return (
    <div>
      <h1>name: {data!.name}</h1>
      <p>height: {data!.height} decimeters</p>
    </div>
  );
}

export default Pokemon;

As you can see, in the Pokemon.tsx component, we use several states to manage errors, loading status, and data, along with a useEffect. We can simplify all of this by using the "swr" package, which allows us to use Suspense to control the asynchronous request that the component’s data depends on.

With this package, the App.tsx component would look as follows:

// App.tsx with Suspense
import { Suspense } from "react";
import "./App.css";
import ErrorBoundary from "./ErrorBoundary";
import Pokemon from "./Pokemon";

function App() {
  return (
    <>
      <ErrorBoundary fallback="There was an error. Ups... :p">
        <Suspense fallback="Is loading...">
          <Pokemon name="charmander" />
        </Suspense>
      </ErrorBoundary>
      <ErrorBoundary fallback="There was an error. Ups... :p">
        <Suspense fallback="Is loading...">
          <Pokemon name="sada" />
        </Suspense>
      </ErrorBoundary>
    </>
  );
}

export default App;

Here you can see, compared to what we had before, that the Pokemon component is now wrapped with the Suspense component, where we specify a fallback component (in this case, simple text saying “Is loading”) that will be displayed while the asynchronous data request for the Pokemon component is being made.

The Pokemon.tsx component would look as follows:

// Pokemon.tsx with Suspense
import useSWR from 'swr';

interface PokemonProps {
    name: string;
}

const fetcher = (url: string) => fetch(url).then((res) => {
  if (!res.ok) {
      throw new Error('Network response was not ok');
  }
  return res.json();
});

function Pokemon({ name }: PokemonProps) {

  interface Pokemon {
    name: string;
    height: string;
  }

  const { data } = useSWR<Pokemon>(`https://pokeapi.co/api/v2/pokemon/${name}`, fetcher, {
    suspense: true
  });

  return (
    <div>
      <h1>name: {data!.name}</h1>
      <p>height: {data!.height} decimeters</p>
    </div>
  );
}

export default Pokemon;

Here we can see how, by using useSWR from the "swr" package, we can make the API request by specifying a fetch method as the second parameter, which will handle making that request to the specified URL. If the response is not satisfactory, it will return an error, which will be handled by the ErrorBoundary. Additionally, as a third parameter, we need to pass an object with the suspense property set to true, so that the Suspense component wrapping this component (as we saw in App.tsx) can be used.

In this simple way, we can make our components that depend on asynchronous data simpler and more readable.

Handle errors with ErrorBoundaries

DuneDev — Sat, 17 Aug 2024 11:25:11 +0000

ErrorBoundaries

In case you wanna handle errors and avoid white screens when some of your components on react fails to render. You can use ErrorBoundary, which is like a component that wrap your piece of code/components that may brake becacose of whatever reason.

In this post we are gonna talk about this method called ErrorBoundary to handle render errors on react.

But first of all, it is important that the error must be a render error not a promise error or anything like that, so ErrorBoundary component can handle it.

Now, let’s take a look how the ErrorBoundary component should look like:

//ErrorBoundary.tsx
import React, { ErrorInfo, ReactNode } from "react";

interface ErrorBoundaryProps {
  fallback: ReactNode;
  children: ReactNode;
}

class ErrorBoundary extends React.Component<ErrorBoundaryProps> {
  state = { hasError: false };

  static getDerivedStateFromError(error: Error) {
    return { hasError: true };
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    console.log(error, info);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

export default ErrorBoundary;

Inside this component we can see this methods:

getDerivedStateFromError: which handles if there was an error or not.
componentDidCatch: inside this methos we can define what are we going to do with the error. In this case is displayed on the console.
render: this method returns the fallback component in case of error or the original component.

To test if this is working as expected. I have created this component call “Pokemon” that make a call to a Pokemon API and in case the pokemon you are searching for is not found, will throw the error so the ErrorBoundary component can display the fallback component:

//Pokemon.tsx
import { useEffect, useState } from 'react';

interface PokemonProps {
    name: string;
}

function Pokemon({name}: PokemonProps) {
  const [data, setData] = useState<Pokemon | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  interface Pokemon {
    name: string;
    height: string;
  }

  useEffect(() => {
    fetch(`https://pokeapi.co/api/v2/pokemon/${name}`)
      .then((response) => {
        if (!response.ok) {
          throw new Error('Network response was not ok');
        }
        return response.json();
      })
      .then((data: Pokemon) => {
        setData(data);
        setLoading(false);
      })
      .catch((error: Error) => {
        setError(error);
        setLoading(false);
      });
  }, []);

  if (loading) {
    return <div>Loading...</div>;
  }

  if (error) {
    //thow here to force a render error so ErrorBoundary can catch it.
    throw error; // Throw error to ErrorBoundary
  }

  return (
    <div>
      <h1>name: {data!.name}</h1>
      <p>height: {data!.height} decimeters</p>
    </div>
  );
}

export default Pokemon;

//App.tsx
import "./App.css";
import ErrorBoundary from "./ErrorBoundary";
import Pokemon from "./Pokemon";

function App() {
  return (
    <>
           {" "}
      <ErrorBoundary fallback="There was an error. Ups... :p">
                  <Pokemon name="charmander" />     {" "}
      </ErrorBoundary>
            <ErrorBoundary fallback="There was an error. Ups... :p">
                  <Pokemon name="asda" />     {" "}
      </ErrorBoundary>   {" "}
    </>
  );
}

export default App;

You can run this example and see how the first Pokemon component is rendered, but the second show the fallback component, that in this example is just a text saying: “There was an error. Ups... :p”.

Understanding Nextjs cache management

DuneDev — Tue, 09 Jul 2024 16:50:17 +0000

Introduction

Next.js is a widely used framework with a variety of utilities that enable more agile and efficient development. However, there is one topic that I find not very easy to understand, and that is how Next.js caches different things.

To better understand this, I should start by explaining that Next.js uses 4 different caches (Router cache, Full Route cache, Request Memoization cache, and Data cache). These are divided into 1 at the client level and 3 at the server level, as shown in the image.

Throughout this post, we will discuss how each of these caches works, whether they are used by default in Next.js 14 and Next.js 15, how to interact with them, and how to bypass them.

Request Memoization cache

This cache belongs to React, not to Next.js per se, but Next.js uses it to cache fetch requests. This means that if the same request is made on a page, it won’t be made twice (in case of two identical requests on the same page). Instead, the value of the first request is returned, having been cached.

At first glance, this is very logical because it prevents repeated requests and thus improves the efficiency of our application. However, there might be specific cases where we need to make the same request within a single page and not receive the cached value as the response for the second request.

If we want to avoid this behavior, we need to pass a "signal" object from "AbortController" in the request options.

async function fetchCarById(id) {
  const { signal } = new AbortController();
  const res = await fetch(`https://myapi.com/cars/${id}`, {
    signal,
  });
  return res.json();
}

This cache is not used by default in Next.js 15, but it is in Next.js 14.

Data cache

This cache is the last one that Next.js consults before fetching data from the API or database. It caches fetch requests so that when multiple users want to get the values of the same request, they are returned from the Data cache instead of making all the requests to the corresponding API/DB. This is especially useful for requests whose values change infrequently, thereby improving performance.

Let's return to the example of requesting car information by its ID.

export default async function Page({ params }) {
  const id = params.id;
  const res = await fetch(`https://myapi.com/cars/${id}`);
  const car = await res.json();

  return (
    <div>
      <h1>{car.modelName}</h1>
      <p>{car.info}</p>
    </div>
  );
}

By using this cache, we can prevent each user wanting information about this vehicle from making a request to the API or database, as this information will not change much.

In Next.js 14, each fetch request in server components is stored in the Data cache by default. This does not occur in Next.js 15, as fetch requests are not cached by default in this version.

This cache is persistent even between deployments of the application. Therefore, it is necessary to know the two ways we can clear this cache. These are:

Time-based Revalidation: This method specifies how often data in this cache is cleared. It can be done in two ways:

The first option is by passing next: { revalidate: 3600 } in the fetch request options, indicating how long the response of this request will remain cached in the Data cache:
```
 const res = fetch(`https://myapi.com/cars/${id}`, {
   next: { revalidate: 3600 },
 });
```

The second option to set a revalidation time is to use the revalidate segment config option. This acts at the page level:

 export const revalidate = 3600;

 export default async function Page({ params }) {
   const id = params.id;
   const res = await fetch(`https://myapi.com/cars/${id}`);
   const car = await res.json();

   return (
     <div>
       <h1>{car.modelName}</h1>
       <p>{car.info}</p>
     </div>
   );
 }

On-demand Revalidation: If your data is not updated on a regular schedule, there's also the option to update the cached value when there's a change in this data. For example, in the case of a blog, it can use the cache unless there's a change and a new post is added.

This can be done in two ways:

Using revalidatePath, a function that takes the path from which you want to clear cached fetch request data:

 import { revalidatePath } from "next/cache";

 export async function publishPost({ post }) {
   createPost(post);

   revalidatePath(`/posts/${post}`);
 }

For more specific clearing, you can use the revalidateTag function.

First, specify a tag in the fetch request options for the data you want to clear from the cache:

 const res = fetch(`https://myapi.com/posts/${id}`, {
   next: { tags: ["post"] },
 });

Then use the revalidateTag function with that tag to identify and clear that request's data from the cache:

 import { revalidateTag } from "next/cache"

 export async function publishPost({ post }) {
   createPost(post)

   revalidateTag(‘post’)
 }

To bypass this cache, you can do so in two ways:

At the request level, by passing 'no-cache' as the value to the 'cache' property in the fetch request options:

   const res = fetch(`https://myapi.com/blogs/${Id}`, {
     cache: "no-store",
   });

2.At the page level, either by converting the page to dynamic and adding the following line at the beginning of page.tsx:

export const dynamic = "force-dynamic";

Or by also adding the revalidate segment config option at the beginning of the page, setting it equal to 0:

export const revalidate = 0;

Full Route cache

The main benefit of this cache is that it allows Next.js to cache static pages during compilation, avoiding the need to generate those static pages on every request. Specifically, it stores the HTML and RSCP (React Server Component Payload) files that make up the page.

Unlike the Data cache, this cache is cleared with each deployment.

You can avoid using this cache in two ways:

By avoiding the use of the Data cache. If Data cache is not used, the Full Route cache will also not be used.
The second way is by using dynamic data on your page.

Router cache

This cache differs from the others we've seen in that it is stored on the client side rather than the server side. It caches the routes the user has visited to pull from this cached data (HTML and RSCP) instead of making a request to the server. By default in Next.js 14, if the route is static, it remains cached for 5 minutes, and if dynamic, it remains cached for 30 seconds. This cache is stored at the user's session level, so if the user refreshes the page or closes the tab, the cached data will be cleared.

We can revalidate the data in this cache using revalidatePath or revalidateTag just like we did with the Data cache. Therefore, if we clear the Data cache using these functions, we are also clearing the Router cache data.

Example of behavior in Nextjs 14 and Nextjs 15

In this example, we are going to show the differences in behavior between versions 14 and 15 of Next.js using the same configuration in both projects. For this, we will need 3 projects.

One that sets up a very simple API with an endpoint that returns a random number.

A project in Next.js 14 and another in Next.js 15, each with a Home page and an About page.

As we can see, the difference between the Home and About pages is that the Home page retrieves the random number by calling the endpoint of the API we created, while on the About page, the random number is obtained through Math.random().

With these projects deployed, we will make a series of observations distinguishing between deployments in development and production mode.

Development Mode

Important: To ensure these examples work, the Next.js Link component must be used for navigating between pages.

Version 14.2.4

In version 14.2.4 of Next.js, the first page that fetches data by calling an external API, regardless of attempts to navigate away and return to this page (home), or even refresh the page from the browser, will consistently return the same value. This indicates that the fetched value is being cached.

Conversely, on the About page, which displays a randomly generated number without making any external calls, refreshing or not will only yield a different/updated number when the page is refreshed from the browser. This behavior is due to Route Cache, which ensures that when navigating between pages and the maximum lifetime of the cached page has not expired, the cached page continues to be served.

Version 15.0-rc

In version 15.0.0-rc.0, the behavior becomes more intuitive, as it does not cache fetch requests by default nor uses Route Cache by default. Regardless of how one navigates through the different pages, accessing them will yield different values each time.

Production Mode

Version 14.2.4

In production mode for version 14.2.4, no numbers change (neither on the home page nor on the about page). Only the about page number changes once when refreshed from the browser. This occurs because the page is cached in Route Cache.

Version 15.0-rc

The behavior in production mode for version 15.0-rc is identical to that of version 14.

Solution

To address the issue of page caching in version 15, a directive can be applied at the top of each page to mark it as dynamic:

export const dynamic = "force-dynamic";

This allows all these pages in version 15 to be built dynamically, preventing Route Cache application and functioning similarly to development mode.

However, in version 14, the only improvement achieved is that upon refreshing the About page from the browser, its value updates. Accessing it via the Link still returns the stored value in the Route Cache of the page. For the Home page, despite version 14 also caching fetch requests by default (unlike version 15), refreshing the page from the browser always yields the same value.

How to unit test async widgets on Flutter

DuneDev — Mon, 01 Jan 2024 18:12:00 +0000

Introduction

First of all. I have to say that i am not an expert on dart or any other programming language, but i've been searching about this topic and did not fount so much information at all, so... Here i am, giving my best to try to give my opion as clear as posible, about how to test a custom widget which content depends on an async call ( like from an API ).

If you are reading this, you may have been struggling as me trying to test the data that comes from an external source inside a custom widget. If this is your case, then keep reading.

Structure

Yes! structure, thats the key. If you are building the widget in a way that the api call that retrieves the necesary data to display inside of it, it's been called (as it looks obvious) from the mothod initState(). You are wrong (as well as i was), becouse in a StatefulWidget, you can not access to the class that holds that initState method or any data at all, becouse it is a private class and the data inside of it can not be accesible from the outside.

There my be some other ways to test this kind of widgets, but in my opinion this is the easiest way.

Services structure

Let's start by imaging we have a repository that has a method that retrieves our data from an API to later feed our widget with that data.

import 'package:dio/dio.dart';

class StarWarsRepository {
  final client = Dio();
  final String BASE_URL = 'https://swapi.dev/api/';

  Future<dynamic> getFilm(int number) async {
    final response = await client.get('${BASE_URL}films/$number');

    if (response.statusCode == 200) {
      return response.data;
    } else {
      throw Exception('Error getting film info');
    }
  }
}

In this case, we are getting info about one film of Star Wars.

Widget structure

Inside my main.dart, I have made a StatefulWidget called testableWidget that it is been call from my root widget MyApp and only displays the title of the movie if there is data.

import 'package:flutter/material.dart';
import 'package:testable_widget/services/api.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: TestableWidget(
        filmData: StarWarsRepository().getFilm(1),
      ),
    );
  }
}

class TestableWidget extends StatefulWidget {
  final Future<dynamic> filmData;
  const TestableWidget({super.key, required this.filmData});

  @override
  State<TestableWidget> createState() => _TestableWidgetState();
}

class _TestableWidgetState extends State<TestableWidget> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('TestableWidget'),
      ),
      body: FutureBuilder(
          future: widget.filmData,
          builder: (context, snapshot) {
            if (snapshot.hasData) {
              final film = snapshot.data;

              return Center(child: Text(film['title'].toString()));
            } else if (snapshot.hasError) {
              return const Center(child: Text('Error obtaining film data.'));
            }
            return const Center(child: CircularProgressIndicator());
          }),
    );
  }
}

The thing here is that we are using the widget FutureBuilder, that let's you create a widget that builds itself based on the latest snapshot of interaction with a [Future]. So we are passing as prop the method from the repository that calls the API.

 home: TestableWidget(
        filmData: StarWarsRepository().getFilm(1),
      ),

Building the widget by this way, the logic reminds outside the widget and it is testable as you can find out trying to run the tests you see below.

Tests

 import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

import 'package:testable_widget/main.dart';

void main() {
  group('TestableWidget', () {
    final filmData = {
      "title": "The Empire Strikes Back",
      "episode_id": 5,
      "opening_crawl":
          "It is a dark time for the\r\nRebellion. Although the Death\r\nStar has been destroyed,\r\nImperial troops have driven the\r\nRebel forces from their hidden\r\nbase and pursued them across\r\nthe galaxy.\r\n\r\nEvading the dreaded Imperial\r\nStarfleet, a group of freedom\r\nfighters led by Luke Skywalker\r\nhas established a new secret\r\nbase on the remote ice world\r\nof Hoth.\r\n\r\nThe evil lord Darth Vader,\r\nobsessed with finding young\r\nSkywalker, has dispatched\r\nthousands of remote probes into\r\nthe far reaches of space....",
      "director": "Irvin Kershner",
      "producer": "Gary Kurtz, Rick McCallum",
      "release_date": "1980-05-17",
      "characters": [],
      "planets": [],
      "starships": [],
      "vehicles": [],
      "species": [],
      "created": "2014-12-12T11:26:24.656000Z",
      "edited": "2014-12-15T13:07:53.386000Z",
      "url": "https://swapi.dev/api/films/2/"
    };

    Future<dynamic> mockGetFilmData() {
      return Future.delayed(const Duration(seconds: 1), () => filmData);
    }

    testWidgets('should display circularProgressIndicator',
        (WidgetTester tester) async {
      await tester.pumpWidget(MaterialApp(
        home: TestableWidget(
          filmData: mockGetFilmData(),
        ),
      ));

      expect(find.byType(CircularProgressIndicator), findsOneWidget);
      await tester.pumpAndSettle();
    });

    testWidgets('should display film title', (WidgetTester tester) async {
      await tester.pumpWidget(MaterialApp(
        home: TestableWidget(
          filmData: mockGetFilmData(),
        ),
      ));

      await tester.pumpAndSettle();
      expect(find.text('The Empire Strikes Back'), findsOneWidget);
    });

    testWidgets('should display error message', (WidgetTester tester) async {
      Future<dynamic> mockErrorFilmData() {
        return Future.delayed(const Duration(seconds: 1),
            () => throw Exception('Error getting film info'));
      }

      await tester.pumpWidget(MaterialApp(
        home: TestableWidget(
          filmData: mockErrorFilmData(),
        ),
      ));

      await tester.pumpAndSettle();
      expect(find.text('Error obtaining film data.'), findsOneWidget);
    });
  });
}