Lady{de}bug – Lady{de}bug

Setting up SonarQube locally

Sat, 20 Sep 2025 00:00:00 +0000

This is not a tutorial. These are study notes on understanding the tool and applying it to small and medium-sized projects in private repositories. Since I already had SonarQube installed on my machine, here is how I configured Docker.

Option 1 — Remove the existing container

I had configured it for a code analysis study project as part of my postgraduate coursework. In this case I reconfigured it for another project; later I will set it up correctly again for the code analysis project.

docker rm sonarqube

Now I can run the command to start a new container:

docker run -d --name sonarqube -p 9000:9000 sonarqube:lts-community

Yes, this is the free version, for learning before paying for something I do not yet know how to use.

Option 2 — Replace the container automatically

To force replacement, use --rm, which removes the container when stopped, or --replace with Podman. With Docker, we generally remove it manually as above.

Option 3 — Check the container status

docker start sonarqube

To stop it, use:

docker stop sonarqube

Run SonarQube locally

Now for the interesting part: configuring SonarQube locally and running a basic scan.

First, some initial configuration. I think this is worth adding to the development setup script.

1. Prerequisites

Java 11 or later installed on the machine; SonarQube needs Java to run.
Docker, optional but it really makes running SonarQube easier.

2. Download and run SonarQube

Download: SonarQube Community Edition

The first step is adjusting Docker, so make sure it is running correctly without problems.

docker run -d --name sonarqube -p 9000:9000 sonarqube:lts-community

Done! SonarQube is running locally.

Adjust the password settings and continue to the page:

SonarQube configuration

Open http://localhost:9000.
Default login:
- Username: admin
- Password: admin

Now let’s configure a project scan.

Generate an authentication token

In the top-right menu, click your user > My Account > Security.
Under “Generate Tokens”, create a token, such as nome-projeto-token.
Save the token; the scanner will use it.

Install SonarScanner

SonarScanner is the CLI that sends your code to SonarQube. Through the local terminal, we tell it to read the project and then obtain the analysis.

Install through NPM for Node projects

npm install -g sonarqube-scanner

For project-specific references, see SonarScanner documentation.

Configure SonarScanner in the project

Create a file called sonar-project.properties in the project root:

Example:

sonar.projectKey=nome-projeto
sonar.projectName=Nome-projeto
sonar.projectVersion=1.0
sonar.sources=.
sonar.language=js,php
sonar.sourceEncoding=UTF-8
sonar.host.url=http://localhost:9000
sonar.login=SEU_TOKEN_AQUI

Problems encountered

ERROR: You’re not authorized to run analysis. Please contact the project administrator.

What does this error mean?

SonarScanner is trying to send the analysis results to SonarQube, but the configured user or token does not have permission to perform this operation on the configured SonarQube project.

Great! Let’s see what I did wrong: the project name in sonar-project.properties did not match the one I configured in local SonarQube.

Now it is ready: running sonar-scanner scans the project and displays the results.

Building a portfolio website and organizing the work I have done

Fri, 06 Nov 2026 00:00:00 +0000

Building a portfolio website and organizing the work I have done

Recently I started organizing my portfolio in a way that would help me present my work more clearly. I wanted more than a list of technologies or repository links. I also wanted to explain what I did, how I organized the stages, and what evidence is available to check each contribution.

The project is on GitHub: https://github.com/kellen-xavier/ladydebug-workstation. The published version is available at https://kellen-xavier.github.io/ladydebug-workstation/.

What I wanted to organize

Throughout my career, I have worked in support, frontend development, mobile and backend applications, testing, and documentation. Some of that work took place in private repositories, so it is not always possible to show the code or reproduce a run through a public link alone.

That is why I am organizing the accounts to distinguish what was implemented, what appears in the available records, and the limits of each piece of evidence. An implementation described in a report does not, by itself, mean that every scenario was executed or that a pipeline was published. I want readers to be able to see that distinction.

A website with several pages

The site is a static application built with React and TypeScript. Instead of creating one long page with every subject mixed together, I divided the navigation into pages for my career, contributions, workflow, setup, tools, and games. The homepage works as a map to reach those sections. This map is still in development, as I would like a layout inspired by Stardew Valley.

For the visual design, I used a retro workstation reference, with cream, beige, brown, and pink tones and a pixel art illustration. I wanted the identity to connect with my Ladydebug blog while keeping the focus on reading and the work presented.

In the In practice section, each contribution can be opened to read its account and references. Public projects also link to their repositories. This keeps the content in one place while giving each subject its own context.

Content separated from components

An important decision was to move long texts out of the components. The introduction, about section, career history, and project accounts live in Markdown files inside src/content/. Components handle the page structure, and content can be edited without changing the layout. Keeping those responsibilities separate made more sense than hardcoding text into components.

For the accounts, I use Markdown with headings, paragraphs, lists, links, and references. The react-markdown library turns that content into page elements. Local images can also be referenced in Markdown; the build process packages the files and generates paths that work on GitHub Pages — see the repository here.

Information with a predictable structure stays in TypeScript. Workflow stages and project data, for example, need an order, identifiers, descriptions, and links. Keeping that data typed helps reveal inconsistencies during development.

This division also makes maintenance easier: editorial content stays in Markdown, data feeding cards and stages stays typed, and components are responsible for presentation.

The workflow is part of the portfolio too

I included a page to record how I usually work. The flow involves understanding the context, building and testing, reviewing evidence, and following up on what needs to improve. The idea is to show some of the decisions and practices behind the deliveries, as well as the final result. I reached this approach through analysis, gathering information, applying tests, and validating the results.

I also organized examples of tools and setup, along with a list of game studies. These sections reflect the subjects I follow and help show how I organize my environment and keep learning. They also include my experience with the Arch Linux-based system Omarchy.

Testing and publishing

The project has unit tests and browser tests with Playwright. In the browser tests, I am prioritizing behaviors someone can perform: navigating between pages, opening an account, following an anchor, downloading a file, copying a command, and filtering the games list. I also check layout behavior at different widths, such as horizontal scrolling and touch target sizes.

I organized the E2E tests into separate files by flow, including navigation, home, career, accounts, workflow, tools, and responsiveness. That makes it easier to locate a scenario and understand which part of the site it covers. The tests validate features and interface states without comparing the wording of editorial texts.

The site is generated as static files and published through GitHub Pages. The pipeline runs lint, type checks, tests, and browser tests against the production build before publishing the main branch version.

What I am still learning

Building this portfolio is also helping me think about presenting technical experience clearly. I need to choose which details help explain a contribution, which links are useful, and where to state limitations instead of making claims that go beyond the available records.

I still want to review the accounts and keep improving navigation and readability on smaller screens. The structure already lets me update each part more independently: I can adjust Markdown text, reorganize a project in the typed data, or improve a component without rewriting the whole site.

The goal is to keep this space as a living record of my work and studies, with ways to check what is public and enough context to understand the rest.

An analysis of PC game releases

Thu, 29 Oct 2026 15:53:10 -0300

Simple but crucial examples of testing in your project.

PC gaming has been growing considerably for a long time, and gaming setups are gaining more space. They compete strongly with, and even surpass, video game consoles in power and performance. They also let people configure their own machines, from entry-level hardware to the latest components, choosing what best suits their needs at a given moment. Improvements include CPUs, motherboards, graphics cards, memory, and peripherals such as keyboards, mice, and monitors.

With PC gaming becoming increasingly prominent, Sony made a major announcement in 2020 about bringing its exclusive PlayStation games to PC. Horizon Zero Dawn was the first release, followed in subsequent years by titles ranging from Days Gone to the award-winning God of War.

Sony gained a dedicated page on Steam, one of the largest PC gaming platforms, followed by its own official site listing releases for these platforms. Games that were once console exclusives can now be played on PC by many more people, including those using entry-level hardware, with excellent performance.

This week, as March draws to a close, we have had some good game releases. Actually, they are not entirely new games: one is a remastered game with performance improvements and graphical fixes, the acclaimed Resident Evil 4.

The other release reaching PC is Sony’s acclaimed exclusive The Last of Us Part I. Anyone who did not play it on PlayStation 3, PS4, or the latest console generation at the time, PS5, can now play it on PC. Or try to play it on PC.

Since its PC release, the game has faced valid criticism from users reporting performance problems on PCs. Even high-end machines cannot run the game without a variety of bugs. Reviews report issues including:

Slow game installation.
Poor graphics optimization, regardless of hardware.
Long shader compilation times, regardless of hardware, especially on high-end PCs considered top-of-the-line setups.
Extremely slow loading, even with the game installed on an M.2 SSD.
Constant crashes: when the game finally loads, it repeatedly closes, putting us back at square one.

The game is clearly having problems. Naughty Dog and Iron Galaxy released a statement and a patch of only 36 MB.

What can we think about this? Testing was missing

The PC release did not have a demo version for users to test. Clearly, the quality team did not test enough, or did not test at all, before approving the release. Performance is far below the available minimum requirements, consuming all the hardware resources even on high-end PCs.

What could cause a system, application, or game to have so many problems?

A lack of seriousness toward the end user: talk to users and release a test version so they can try it on their devices or platforms and see how it behaves. Involving real users in development should not be a challenge or something to fear. If the team is afraid to show its work, something is wrong.

Not talking to your team: sometimes, and often, the team does not communicate or interact. That is the perfect recipe for disaster. A daily meeting should not be a status report. Technical conversations need enough clarity, with collaborative work and minute-by-minute communication. When the team communicates this way, daily or weekly ceremonies are unnecessary because everyone already understands what is happening and how things stand.

Not including quality from the start: a new project should include testing and refinement and validation of the collected requirements, remember the users and the defects found in code and documentation. Every development activity has a corresponding testing activity. Testing involves every stage of the software development lifecycle. What are the priorities, risks, product type, and project goals? It may be necessary to combine and organize tests and their levels.

Not completing testing: review defect reports, create a test summary for project management, analyze lessons learned from defects and reports, and improve process maturity. How can a stage or task be finished without completing its testing?

A lack of test work products: work products are deliverables from each testing activity. We need planning, through a test plan, and analysis of conditions, defects, and priorities. We also need monitoring and control, through progress, summary, and completion reports.

Managing fear: when afraid, we communicate less, hesitate often, and withdraw from recurring feedback. A team that manages fear communicates clearly and frequently. It does not hesitate to learn something new and share it. It asks for more feedback to seek improvements.

We can imagine something at this level happened during the game’s development. How do we know? The result is there. It is unacceptable to keep seeing errors like these in games. Let us use good practices and understand the importance of software testing throughout the project and process. Now we can only wait for new fixes and a drastic improvement as soon as possible.

Sources for research and reading

TDD — Test-Driven Development — Kent Beck — Book here.

Link to Naughty Dog feedback.

Adrenaline video: The Last of Us Part 1 on PC — testing hardware live! Adrenaline video: Resident Evil 4 Remake — is it good on PC? [review]

Adrenaline video: The Last of Us Part 1 — five reasons it is one of the worst ports ever made.

A tip for improving team communication

Try tools people feel comfortable with. Examples for communication are Gather Town and Discord.

Create relaxed environments that bring clarity to communication and help people understand their colleagues better.

Take part in code reviews and project development too.

Refactoring my blog

Fri, 10 Jul 2026 00:00:00 +0000

Analysis of the notion-blog repository

My personal blog was full of bugs because I had not done the necessary maintenance since creating it, perhaps two years ago. Now the idea is to fix bugs and add features I would like.

Broken pagination, slow loading, and content centralized in one tool.

What I want to improve: decentralize the content, organize routine versioned backups, and deploy to dev as well as main.

1. Overview

It is a static Next.js blog using Notion as its CMS/backend. It is a fork of the original ijjk/notion-blog template, customized by me. Post content lives in a Notion table, and the site is generated through SSG, Static Site Generation, with incremental revalidation, hosted on Vercel.

Current deployment: https://notion-blog-lake-two.vercel.app/
Current branch: claude/repository-analysis-ieglo6, identical to develop, with no differences.
License: present, license.

2. Stack and dependencies

Layer	Technology
Framework	Next.js `^11.1.2`, Pages Router
UI	React `17`, CSS Modules
Language	TypeScript `5.8`, with `strict: false`
Content	Unofficial private Notion API, `www.notion.so/api/v3`
Extras	`katex`, equations; `prismjs`, syntax highlighting; `@zeit/react-jsx-parser`; `async-sema`, rate limiting; `github-slugger`
Quality	Prettier, lint-staged, pre-commit
Deployment	Vercel

3. Structure

src/
├── pages/
│ ├── index.tsx # Home
│ ├── contact.tsx # Contato (GitHub/LinkedIn)
│ ├── blog/index.tsx # Lista de posts (getStaticProps)
│ ├── blog/[slug].tsx # Renderiza 1 post (getStaticProps/Paths + fallback)
│ └── api/ # asset.ts, preview.ts, preview-post.ts, clear-preview.ts
├── lib/notion/ # Integração com o Notion (rpc, getBlogIndex, getPageData…)
├── lib/build-rss.ts # Gera feed Atom em /public/atom no build
├── components/ # Header, Footer, Code, Equation, Counter, SVGs, SpotifyPlayer…
└── styles/ # CSS Modules + global.css
scripts/create-table.js # Cria a tabela-modelo no Notion via API privada

4. How it works — Data flow

rpc.ts sends authenticated POST requests to Notion’s private endpoint using the token_v2=$NOTION_TOKEN cookie.
getBlogIndex loads the table, BLOG_INDEX_ID, builds the post map through getTableData, which interprets the Notion collection schema, and fetches previews for the 10 most recent posts with concurrency limited to three through async-sema. It uses disk caching, .blog_index_data*, during builds, USE_CACHE.
blog/index.tsx filters drafts in production, Published === 'Yes', and lists posts.
blog/[slug].tsx retrieves post content through getPageData and paginated loadPageChunk, resolves tweet embeds, and uses a large switch to convert each Notion block type into JSX: text, header, image, code, quote, callout, equation, bookmark, tweet, and others.
api/asset.ts acts as a proxy: it retrieves the signed Notion file URL with getSignedFileUrls, then redirects with status 307 to serve images and videos.
build-rss.ts runs at build time and generates the Atom feed at /public/atom.
Preview mode: api/preview.ts and preview-post.ts enable Next’s draft mode.

5. Strengths

A lean architecture with clear separation between lib, pages, and components.
Correct use of SSG with revalidate, ISR, and fallback: true.
Preview-fetch rate limiting and build caching.
Rich Notion block support: KaTeX equations, Prism code, callouts, bookmarks, videos, tweets.
Formatting tools: Prettier and lint-staged.

6. Problems and risks I found

Security and practical concerns

NOTION_TOKEN used as the preview password: preview.ts and preview-post.ts compare req.query.token === process.env.NOTION_TOKEN. This puts the secret Notion token in the URL, exposing it to logs, history, and referrers. A separate secret such as NEXT_PREVIEW_SECRET should be used.
Private Notion API, token_v2 and /api/v3: unofficial, potentially subject to breaking changes, and the token is your personal session. The preferred approach is migration to the official Notion API, @notionhq/client.
api/asset.ts is an open proxy, Access-Control-Allow-Origin: *, signing URLs for any supplied assetUrl or blockId. It is worth restricting.

Undeclared dependencies

node-fetch, @next/env, and shell-quote are imported but absent from package.json, working only through transitive dependencies or hoisting. This is fragile and can break builds with a clean lockfile. They should be explicit dependencies.

Leftovers from the original template and inconsistent branding

header.tsx: the Source Code link and OG image point to ijjk/notion-blog and notion-blog.now.sh, whose now.sh domain is disabled; Twitter points to @_ijjk.
footer.tsx: links to ijjk’s repository.
index.tsx: still uses the Vercel + Notion image and branding.
Generic metadata and <title>, such as My Notion Blog and An example Next.js site…
Mixed Portuguese and English in the interface.

Potentially broken or fragile code

Tweet embeds use api.twitter.com/1/statuses/oembed.json, the discontinued v1 API, and probably no longer work.
[slug].tsx uses unstable_revalidate, an old API ignored in Next 11, alongside revalidate.
equation.tsx: render() can return undefined if an error is not a ParseError, because result is never assigned.
getPageData removes table blocks with a fixed splice(0, 3), which is brittle.
Inconsistent Node versions: the README asks for Node >=18, but getBlogIndex.ts uses Array.prototype.toSorted(), requiring Node 20+. Meanwhile, vercel.json forces -openssl-legacy-provider as a workaround for old builds. I recommend explicitly fixing Node 20.

Quality and maintenance

tsconfig uses strict: false, reducing type safety, with many uses of any.
No tests or CI, with .github/ absent.
Small README errors, such as using ´´´ instead of Markdown code fences.

7. Prioritized recommendations

Replace the preview secret with a dedicated variable, avoiding NOTION_TOKEN in the URL.
Declare node-fetch, @next/env, and shell-quote in package.json.
Update branding: links, OG image, title, and Twitter should use mine, removing ijjk and now.sh leftovers.
Fix or remove tweet embeds, the dead v1 API, and unstable_revalidate.
Align the Node version, fixing engines: node >=20 because of toSorted().
In the medium term, migrate to the official Notion API and consider upgrading Next.js from version 11 for security and performance.

Blog fixes

First I requested an analysis through claude.ai, then wrote the following instructions:

📚 claude/repository-analysis-ieglo6? I can start with low-risk, high-impact changes: package.json dependencies, branding, the preview secret, and small bugs. Since this was an analysis task, I have not made changes yet.

Implement as follows.

Fix the issues and always run the necessary tests. Do not implement without testing.

Open PRs after validation tests.

Handle sensitive updates carefully to avoid breaking production.

Document changes only in my kellen-xavier repository.

Create /docs for documentation.

Do not share keys or sensitive data, including in documentation or README.md.

Create an .agents setup for persistent information.

Include .AGENTS.md in the setup.

Pay attention and test at every step.

Stage	Change	Validation
Dependencies	Declared `node-fetch@2.6.1`, `@next/env@11.1.2`, `shell-quote@1.7.2` as dev, and `@types/node-fetch`; added `engines.node >=20` and typecheck/test scripts	Passing tsc
Security, sensitive	Dedicated `PREVIEW_TOKEN` in `src/lib/preview-auth.ts`, with fallback to `NOTION_TOKEN` to avoid breaking production	Four tests: 401, 404, success, fallback
Branding	Removed ijjk and now.sh leftovers from header, footer, and server constants	Regression test
Bugs	`equation.render` never returns undefined; `unstable_revalidate` replaced by `revalidate`; dead v1 tweet oEmbed replaced by `publish.twitter.com`	Render test and build
Docs	/docs with SETUP, ARCHITECTURE, SECURITY, CHANGELOG, only in my repository	—
Agents	AGENTS.md in the root and .agents/ for persistent context and conventions	—

For .AGENTS.md, with a leading dot, I used the standard AGENTS.md convention at the root, the name agent tools recognize, plus an .agents/ folder for persistent setup.
The PR targeted develop, the repository’s default branch, in four thematic commits.

How did it turn out?

I was still using Notion, but wanted to extract all the text and keep it in my own repository. That started the migration to a different layout: the Hextra template. I used AI to migrate the posts first. Since Notion can export Markdown files, moving everything at once was simpler. Then I configured the new template, added the features I wanted, and adapted its cleaner, simpler layout. This continues in “Refactoring the blog — part 2”, which is still a draft.

Bot Planner — Tracking personal development work

Mon, 06 Jul 2026 00:00:00 +0000

Recently I have been developing some AI study projects, and I needed a way to organize how long I spent working on them: elapsed time.

While developing something, I usually read language documentation for practices, collect document links, and write documentation for particular project features. I also remember tasks while working and notice things I can finish right after the current task. Add comments about what was done, and that is the general tracking I needed.

Based on that problem, I thought of something practical to use during development: /inicio when starting an activity, /link to add documentation and other important references, /nota for notes and comments, task to create tasks, and fim when finishing everything. Afterward, it should generate release notes describing completed work and pending tasks.

Then I read a blog post and thought of creating a personal management bot to support my development cycle with little friction and generate notes at the end of the work.

It could also be used for sharing with someone on the team, following XP-oriented development.

I created the repository at https://github.com/kellen-xavier/ladydebug-bot-planner, ~~initially private, with plans to release it afterward~~, now open source. I am fixing some security issues and first creating the bot. Initially interaction is through Discord, but it will support multiple communication channels. I mainly considered Slack and Discord; the others did not particularly interest me.

First development phase

During initial testing, commands cluttered the unified chat. I considered creating a second text channel for separate release notes, making it easier to review the following day with a clear distinction between commands and release notes.

Bot organization

Configuring the bot is straightforward. Follow the official documentation: Building your first Discord bot.

Configuring the bot for this case study:

Go to the Discord Developer Portal.
Open the ladydebug-bot-planner app.
Go to Bot.
Click Reset Token.
Copy the new token.
Update DISCORD_TOKEN in .env.

Run again:

set -a; source .env; set +a
python -m daily.main

Set up the minimum local configuration.

Your local .env should contain at least:

DISCORD_TOKEN=token_do_bot DISCORD_GUILD_ID=807481361916100628 DB_PATH=daily.db

Bot Planner test plan

Overview.

Checklist:

All items

[•] Map existing modules and features in src/daily. [ ] Map existing tests by feature. [ ] Run available tests and coverage. [ ] Consolidate coverage gaps and recommendations.

Features with tests

I created the report at docs/TEST_COVERAGE_REPORT.md, documenting:

Current suite status: 79 passed.
Guidelines for avoiding biased tests and false positives.
Remaining gaps by priority.
Exact scenarios to implement.
Acceptance criteria for subsequent rounds.
A recommendation to add pytest-cov.
Suggested execution order.

Main areas prioritized in the report:

CommandRouter.
SqliteStorage.
SimpleFetcher.
VCS adapters.
End-of-day report.
Discord adapter callbacks.
Models/DTOs.
Objective coverage measurements.

Errors encountered:

python -m daily.main
2026-07-09 09:32:45 INFO discord.client logging in using static token
2026-07-09 09:32:47 INFO discord.gateway Shard ID None has connected to Gateway (Session ID: b25a5b78274ede64c286f2fc11e8c2e3).
Bot online como ladydebug-bot-planner#3088
2026-07-09 09:51:05 ERROR discord.app_commands.tree Ignoring exception in command 'inicio'
Traceback (most recent call last):
 File "/home/kellen/Documents/Projetos github/ladydebug-bot-planner/.venv/lib/python3.14/site-packages/discord/app_commands/commands.py", line 859, in _do_call
 return await self._callback(interaction, **params) # type: ignore
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "/home/kellen/Documents/Projetos github/ladydebug-bot-planner/src/daily/adapters/discord_bot.py", line 90, in inicio
 msg = router.inicio(str(interaction.user.id), str(interaction.channel_id))
 File "/home/kellen/Documents/Projetos github/ladydebug-bot-planner/src/daily/command_router.py", line 32, in inicio
 s = self._day.start_day(user_id, channel_id)
 File "/home/kellen/Documents/Projetos github/ladydebug-bot-planner/src/daily/core/day_service.py", line 32, in start_day
 raise DayAlreadyOpen("Já existe um dia aberto para este usuário.")
daily.core.day_service.DayAlreadyOpen: Já existe um dia aberto para este usuário.

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
 File "/home/kellen/Documents/Projetos github/ladydebug-bot-planner/.venv/lib/python3.14/site-packages/discord/app_commands/tree.py", line 1302, in _call
 await command._invoke_with_namespace(interaction, namespace)
 File "/home/kellen/Documents/Projetos github/ladydebug-bot-planner/.venv/lib/python3.14/site-packages/discord/app_commands/commands.py", line 884, in _invoke_with_namespace
 return await self._do_call(interaction, transformed_values)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 File "/home/kellen/Documents/Projetos github/ladydebug-bot-planner/.venv/lib/python3.14/site-packages/discord/app_commands/commands.py", line 877, in _do_call
 raise CommandInvokeError(self, e) from e
discord.app_commands.errors.CommandInvokeError: Command 'inicio' raised an exception: DayAlreadyOpen: Já existe um dia aberto para este usuário.

Reason:

DayAlreadyOpen: a day is already open for this user. This happens because /inicio opened a session in daily.db, and then /inicio was called again without first closing it with /fim.

Explanation:

Technical cause: the core correctly prevents two days from being open:

if self._storage.get_open_session(user_id) is not None:
 raise DayAlreadyOpen("Já existe um dia aberto para este usuário.")

The problem is that this exception reaches Discord and produces a stack trace. The bot should respond with a friendly message, such as: “You already have an open day. Use /fim to close it before starting another.”

Corrections:

Adjustment plan: still in planning mode, so no files will be edited yet. The recommended changes are:

Handle DayAlreadyOpen in CommandRouter.inicio.
Handle NoOpenDay in /nota, /link, and /fim.
Prevent expected core exceptions from becoming Discord errors.
Improve Discord environment diagnostics with DISCORD_CLIENT_ID.
Document local and production configuration in the README.
Add tests for these cases.

Expected behavior after the adjustments

Validate /inicio with a day already open and activities unfinished. Expected message:

🟡 You already have an open day. Use /continuar to resume your day.

Behavior: submitting /continue should continue adding activities to the day. In other words:

Scenario:

Given the user sends /iniciar on day 1, and sends /iniciar again on day 1, when the message returns, “🟡 You already have an open day. Use /continuar to resume your day,” then the user should enter /continuar and continue until finishing the day.

Validate /nota without an open day. Expected message: ⚠️ No open day. Use /inicio first.

Validate /fim without an open day. Expected message: ⚠️ No open day to close. Use /inicio to start.

Validate /link without an open day. Expected message: ⚠️ No open day. Use /inicio first.

Files that should change

src/daily/command_router.py
src/daily/adapters/discord_bot.py
src/daily/main.py
.env.example
README.md
tests/test_ingest_and_report.py
tests/test_discord_bot.py
tests/test_main_config.py

What changed:

src/daily/command_router.py.
/inicio with an open day now returns: 🟡 You already have an open day. Use /continuar to resume your day.
New continuar method.
/nota, /link, and /fim now handle NoOpenDay with friendly messages.
/link checks for an open day before fetching and summarizing a URL.
src/daily/adapters/discord_bot.py.
Added the Discord /continuar command.
Improved diagnostics when the bot cannot see the server.
If DISCORD_CLIENT_ID is configured, the error prints the correct invitation URL.
src/daily/main.py.
Added environment validation: DISCORD_TOKEN is required; DISCORD_GUILD_ID and DISCORD_CLIENT_ID must be numeric when supplied.
.env.example.
Added DISCORD_CLIENT_ID.
README.md.
Documented /continuar.
Documented local and production environments.
Added Discord troubleshooting.
Added tests for /inicio with an open day.
Added tests for /continuar with and without an open day.
Added tests for /nota, /link, and /fim without an open day.
Added tests for DISCORD_CLIENT_ID and DISCORD_GUILD_ID validation.
Added tests for the invitation URL in diagnostics.

Overview of Discord tests

Updates and improvements

A second text channel was added. The /fim command finishes the report and adds the day’s release notes to the channel that made the call.

We then noticed that activities created during the day need to be completed. This leads to the next feature.

Feature: given that a user completes a created task, they should submit /fim-task with the following action.

Expected behavior:

URL: add the link to the completed activity. Task title: my task’s name. Time the activity was open: xx minutes / xx hours / xx days.

Given that the activity contains a comment, when the action is completed, then the release notes should display the comments added to that action.

Production workflow

Create a #release-notes channel.
Copy its channel ID.
Create an app/bot in Discord.
Invite the bot with bot applications.commands.
Create a Railway project connected to GitHub.
Configure secrets on Railway.
Configure persistent storage.
Start command: python -m daily.main.
Deploy.
Test in Discord:

/inicio
/nota
/pr url:https://github.com/…/pull/…
/fim

Crush coding agent with TUI and UI on Windows

Sun, 11 Jan 2026 00:00:00 +0000

Continuing my terminal and TUI studies, here I explore CRUSH on a Windows machine: how I configured it and how it has worked so far. I tested it with a simple open-source repository for setting up a Windows development environment.

Main goal

Let developers use AI assistance directly in the terminal, without switching to a web editor or an IDE with integrated plugins. It is also lighter to run than VS Code, for example. The tool offers:

Integration with multiple AI model providers.
Sessions with project context preserved.
An optional interactive TUI, Text User Interface.
A traditional CLI for automation or scripts.
Extensibility through standards such as Agent Skills and MCP, Model Context Protocol.

Source: Crush on GitHub

My first test on Windows

Using it on a Windows machine

Installation: in PowerShell, I chose this command:

# NPM
npm install -g @charmland/crush

That part was straightforward. To integrate the OpenAI API, first create an API key. I followed their Windows quickstart. Copy your key and set it aside in a text note. After installing CRUSH on Windows, the configuration lives under C:\Users\SEU_USER, specifically C:\Users\<SEU_USUARIO>\.config\crush\.

If the folder does not exist, create it with mkdir $HOME\.config\crush. Then continue integrating an AI provider, OpenAI in this case. Below are the PowerShell commands for first creating an environment variable.

Create an environment variable

setx OPENAI_API_KEY "sua_chave_aqui"

As usual, close the terminal and start a new one. Check it with echo $Env:OPENAI_API_KEY.

Check that Crush works with crush --version. If the version is displayed, start it:

crush

PowerShell loads the tool’s UI, and you can begin. For this test I decided to refactor a Windows setup project: https://github.com/kellen-xavier/scripts-config-windows. It is not particularly exciting, but it is necessary and useful when reinstalling the environment. First I downloaded the repository through VS Code. Yes, I used the editor for now, although the other Charmbracelet plugins offer customization. That is not the focus here.

Practical use

Ask about the current project’s code. In this case, I went to my project folder:

cd meu-projeto
crush

My first request was to analyze the project in general terms, looking for possible bugs. It then returned its findings.

analyze possible errors

I had forgotten to create AGENT.md. CRUSH itself recommends it on screen, so I went ahead and created it. This is the original instruction block:

# Arquivo de script PowerShell para configuração Windows
Repositório de scripts voltado para Windows: instalar e personalizar via Shell Script. Este repositório foi criado com o intuito de facilitar a instalação de Aplicativos Windows. Criar o arquivo programas-new-apps.ps1

## REGRAS: O script deve conter
- Implementar Testes com Pester
- Usar análise estática de código
- Usar winget como gerenciador principal
- Instale programas com segurança usando winget
- Verificar se o winget está instalado
- Instalar programas de forma idempotente (não reinstalar se já existir)
- Usar parâmetros silenciosos
- Gerar log de execução
- Falhar de forma segura em caso de erro
- Não baixar executáveis diretamente da internet
- Seguir boas práticas de segurança no Windows
- Download e Execução de Script Externo com validação (Win11Debloat)
- Instalar gerenciadores de versão (Instalação de Múltiplas Versões do Java/Node.js)
- Deve conter blocos de help
- Script verifica conectividade antes de tentar downloads
- Adicionar Suporte a -WhatIf e -Confirm
- Transformar scripts em módulo PowerShell com funções reutilizáveis
- Consistência nos Nomes dos Scripts
- Verificação de Código de Saída (uso de $LASTEXITCODE para validar sucesso das operações winget)
- Feedback Visual ao Usuário (uso de Write-Host com cores para indicar status das operações)
- Todos os scripts principais possuem verificação de permissões administrativas no início

List common software examples

Work VPNs

VPN: Netskope Client.

Applications

Android Studio, BlueStacks 5, Bitwarden, Cursor, Docker Desktop, DBeaver Community, Discord, Flameshot, Global VPN Cliente, LibreOffice, Powershell, PowerToys Awake, Intellij IDEA Community Edition, ScreenToGif, sqldeveloper, Sublime Text Free, Teams, Insomnia, Obsidian, VS Code, Visual Studio Installer, Logitech G Hub.

Browsers

Google Chrome, Edge, Firefox, Opera.

Development languages

JAVA 11, 17, 18+.
NodeJS.
Python.

README.md documentation

Specify the minimum Windows 10 version: 1809+ is required for winget.
Require an up-to-date App Installer.
Include troubleshooting.

Registry backup

$BackupPath = "$PSScriptRoot\backup\registry-$(Get-Date -Format 'yyyyMMdd-HHmmss').reg"
reg export "HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize" $BackupPath

Correction priorities for the existing scripts

Priority 1, security: add hash validation for Win11Debloat, back up the registry before changes, and implement Try-Catch in every script.
Priority 2, functionality: implement persistent logging, add prerequisite checks, and correct the default-browser command.
Priority 3, maintainability: add script parameters, implement idempotency, and add comment-based help.

References

I tried to include everything I understood to be appropriate for creating this setup. I also had to read the references to understand the best practices. It is important to understand exactly how to structure the AGENT file.

Then I asked it to execute the AGENT file: based on the AGENT.md file execute.

Based on the first command, it returned:

Processing the AGENT file:

I opened VS Code to see how it was behaving:

Running lint:

Running tests:

I asked for a README.md update:

Final project structure:

A BPMN cheat sheet

Mon, 01 Sep 2025 00:00:00 +0000

For anyone starting to draw flowcharts, here are the BPMN event options.

Start begins the flow, intermediate happens along the way, boundary attaches to an activity to handle something, and end finishes the path. The rule of thumb: catch waits for something; throw triggers something.

Start events

Start event, none: starts without a condition.
Message start: starts when a message arrives, such as a webhook.
Timer start: schedule/cron, using a date, delay, or repetition.
Conditional start: starts when an expression becomes true.
Signal start: starts upon receiving a broadcast signal.

Intermediate events

Message intermediate, throw: sends a message to another participant.
Timer intermediate, catch: waits for a time or date.
Escalation intermediate, throw: raises an escalation without treating it as an error.
Conditional intermediate, catch: pauses until a condition becomes true.
Link, catch/throw: a jump within the same diagram, connecting points.
Compensation intermediate, throw: triggers compensation to undo something.
Signal intermediate, catch/throw: publish/subscribe broadcasting; any listener can receive it.

Boundary events attached to a task or subprocess

Trigger when something happens during the activity.
Interrupting, solid border: cancels the activity and redirects the flow.
Non-interrupting, dashed border: creates an alternative flow without cancelling the activity.
Common types: Timer, Message, Conditional, Signal, Escalation, Compensation.

Special cases

Error boundary: interrupting only; catches errors from the subprocess.

Cancel boundary: only on a Transaction subprocess.

Non-interrupting variations keep the activity running.

End events

Message end: sends a message and ends.
Escalation end: notifies the level above and ends.
Error end: throws an error; leaves the subprocess until an error boundary catches it.
Cancel end: cancels a Transaction.
Compensation end: requests registered compensations.
Signal end: emits a broadcast signal and ends.
Terminate end: terminates all active activities in the process or subprocess.

Understanding terminals and everyday Git commands — part 1

Tue, 17 Jun 2025 00:00:00 +0000

This post started as a few practical Git commands for everyday use. But I had no written collection of terminal studies either: what a terminal is, how to use one, and where to read more before getting into Git commands.

I always say it is important to know how to use the terminal. At a minimum, we need to know how to use these tools. There is no avoiding it, even if your IDE is perfect and entirely visual, because we will inevitably face problems outside the visual interface.

I like the driving analogy: imagine you are driving a car, it beeps and stops, and you need to open the hood to find out what happened. It could be a fully automatic BYD, but the car still contains logs and a black box called an EDR, Event Data Recorder. Here I use the expression “get your hands dirty” and encourage not being afraid of these commands. Understanding what happens under the hood brings much deeper clarity.

Some important basic concepts

What is a terminal?

A terminal is a text interface for interacting directly with the operating system. It sends commands to a shell, such as Bash, Zsh, or PowerShell, which interprets and executes instructions through system APIs.

Terminal references — Reading and videos

Wikipedia [Akitando] #70 — Understanding Git, not a tutorial [Akitando] #71 — Using Git properly and cleaning up commits

File system and navigation

Generally, navigating in a terminal means entering and leaving folders and handling files. It is like navigating a visual interface, but with commands. When we say “do this in the project/automation repository”, we mean inside that folder.

Visually, we have a screen and somewhere to navigate. When opening a terminal on Windows, for example, you may see C:\Users\meu.nome\Sua-pasta. In the screenshot, this would be something like C:\Users\kellen.xavier\Documents\Estudos\docs-estudos-obsidian. My personal organization puts projects in Documents, inside the study folder. So when I say “enter the Obsidian study project and run git pull”, that is the location I mean.

For example, here is a folder I need to reach through the terminal. When opening it, most people will see something like:

PS C:\Users\kellen.xavier>

Then we use commands to navigate there.

Commonly used commands

Navigation:

pwd # mostra o diretório atual
ls # lista arquivos e pastas
ls -la # lista detalhada (inclui ocultos)
cd pasta # entra na pasta
cd .. # volta um nível
cd ~ # vai para a home

In order, these commands show the current directory, list files and folders, show a detailed listing including hidden files, enter a folder, go up one level, and go to the home directory.

Clicking the address bar shows the path starting from kellen.xavier, in my case. My location is C:\Users\kellen.xavier\Documents\Estudos\docs-estudos-obsidian, so in the terminal:

cd Documents\Estudos\docs-estudos-obsidian

Now I have entered the folder:

Git

Here is a sequence of useful commands, especially when working on projects with more than one contributor. Do not forget them.

To merge your current branch into the main branch, follow these steps:

git checkout sua-branch
$ git fetch origin # Puxa as últimas informações do repositório remoto
$ git rebase origin/main
# Atualiza sua branch com as alterações da branch main

$ git rebase origin/main # Atualiza sua branch com as alterações da branch main

After updating your development branch, use git checkout to switch to develop or main:

git checkout develop

Now you are on develop. Merge your development branch with this command:

git merge sua-branch

A brief note on pull requests

Creating a pull request, PR, on GitHub or another version control platform proposes changes collaboratively and in a controlled way. A PR asks for changes on a specific branch to be reviewed and, if approved, merged into the project’s primary branch, such as main or develop.

Consider this scenario: if you need to work specifically on a branch other than main, create a local branch based on the desired remote branch. Suppose you want to work on minha-branch.

Use this Git command:

git checkout -b minha-branch origin/minha-branch-remota-desejada

This creates a local branch called minha-branch based on the remote origin/minha-branch-remota-desejada branch.

You can then work on the local branch, committing and performing other operations as usual.

Everyday commands:

Before starting development, update your local environment from the remote repository.

git pull

This updates the local environment with changes made by the project’s other contributors.

The git pull command fetches the latest changes from a remote repository and then merges them into your current branch. In other words, it combines git fetch and git merge.

Another git pull example:

git pull <remote> <branch>

Here, <remote> names the remote repository you want to pull from, usually origin, and <branch> is the remote branch, such as main or develop.

Committing changes

To send changes to the remote repository, stage them and write a message describing what changed.

Stage a change:

git add .

⚠️ Be careful with git add .: it stages every change. Avoid using it indiscriminately; prefer:

git add nome-do-arquivo-ou-pasta

Then write the commit message:

git commit -m "padrao-de-commit: minha mensagem"

Read more about commit conventions here; the link will be added later.

Now check your terminal. If there are no errors or conflicts, upload the changes:

git push

To merge your branch into main in the repository, use:

git merge sua-branch

About git stash

The git stash command temporarily stores changes from your working directory, allowing you to return to the repository’s earlier state without committing them. This is useful when switching quickly between tasks or branches while preserving work that is not ready to commit.

Here are some examples:

Temporarily store changes: if you have made changes but do not want to commit them yet, use:

git stash save "Descrição opcional"

The description is optional and helps identify why you stashed the changes.

List stashes: list the stashes you created:

git stash list

Apply a stash: apply the most recent stash or a specific one:

git stash apply # Aplica o stash mais recente
git stash apply stash@{n} # Aplica um stash específico pelo seu índice

Remove a stash: after applying one, you can remove it:

git stash drop # Remove o stash mais recente
git stash drop stash@{n} # Remove um stash específico pelo seu índice

Create a branch from a stash: create a new branch based on a stash:

git stash branch nova-branch # Cria uma nova branch e aplica o stash nela

Other important points:

Update your branch with the latest changes from main to help avoid merge conflicts:

git fetch origin # Puxa as últimas informações do repositório remoto

git rebase origin/main # Atualiza sua branch com as alterações da branch main

⚠️ Attention

Do not use git pull in these situations. Read the explanation of git pull again.

A development testing workflow based on the test pyramid

Thu, 05 Jun 2025 00:00:00 +0000

1. What is development testing?

Before moving a card to QA, the development team should validate its code with systematic tests at different levels: unit, integration, and functional. This reduces rework and improves software quality.

2. Structuring the tests

The test pyramid suggests:

Read the user stories, their tests, and their acceptance criteria.
Unit tests, at the base: validate isolated pieces of code, such as functions and methods.
Integration tests, in the middle: ensure different parts of the system interact correctly.
Functional/E2E tests, at the top: validate the complete user flow.

3. How can this be applied to a bug?

Step 1 — Unit test

✅ Write tests for the query that retrieves the correct domain from the database.

Check that the query returns only domains of the blog type.
Ensure the first domain is not selected indiscriminately.

Unit test example with PHPUnit:

public function testBuscaDominioCorreto() {
 $dominio = new DominioRepository();
 $resultado = $dominio->buscarPorTipo('blog');
 $this->assertNotEmpty($resultado);
 $this->assertEquals('blog', $resultado->tipo);
}

Step 2 — Integration test

✅ Validate that SaveSessionsUrlAnalyticsJob.php correctly saves data to the analytics_session_urls table.

Simulate running the job with different domain scenarios.
Check that the data is recorded correctly.

Step 3 — Functional test, if needed

✅ Run the complete functionality and validate that RPS reports display the expected data.

4. How can the team adopt this?

Before opening a bug, ensure the code passed unit and integration tests.
Adopt a development testing workflow: Developer implements – Code review – Development testing – QA.
Record test evidence and include a PR, avoiding handing off code without prior verification.

How to add evidence:

Tests running in the development environment: local validation, even with Docker, is not sufficient here because various environment and network factors have not been checked against the requirements. This can produce a false positive. Local tests belong to other testing categories, such as the unit tests mentioned above.

Use the development environment.
Include screenshots for end-to-end tests.
Attach PRs to the card.
Validate the test scenarios on the card. If they are missing, notify the responsible QA person.

Adding shift-left testing to the quality process step by step

Thu, 05 Jun 2025 00:00:00 +0000

Here is a brief overview of introducing a basic quality process to a team.

Goal — Use a backlog to refine user stories for development: create a backlog of testing tasks and activities from the beginning of the development cycle.

Write user stories with acceptance criteria, splitting complete flows into features: identify testing requirements for each feature through user stories. Include clear, specific acceptance criteria so every feature can be tested properly.

Develop test cases for each user story: write test cases that cover all aspects of the feature described in the story. Include both success and failure scenarios, covering different usage paths.

Perform static testing and analysis before development: review documents and perform static code reviews to identify potential problems before development begins. Use static analysis tools to identify possible vulnerabilities or errors in the source code.

Integrate automated tests into the development pipeline: automate unit, integration, and regression tests to protect the stability of developed features. Integrate those tests into the development pipeline for continuous execution after each code change.

Implement continuous reviews and iterative feedback: continuously review code and features under development to identify and correct problems quickly. Use iterative feedback with developers and the quality team to improve development.

Document and analyze quality and performance metrics: record quality metrics, test coverage, and software performance to assess testing effectiveness and identify improvements. Regularly analyze test results to adjust testing strategies as needed.

Do you still need Testing Library when an element has a data-cy attribute?

Thu, 05 Jun 2025 00:00:00 +0000

Below is an example of code that uses data-cy to locate elements in Cypress E2E automation.

Using Testing Library is useful when an element has not been defined for E2E testing, meaning it has no data-test/cy attribute. For Testing Library to recognize it in the automation, the element Cypress searches for should not have data-cy; Testing Library then finds it using the pattern findByText.('Sua palavra mágica').click();.

Option 1 — Configure the setup-tests.js file, Cypress v10+:

Create setup-tests.js if it does not exist, in the project root or another location specified by your Cypress configuration. See the documentation for details.
Configure the testIdAttribute attribute:

// cypress/support/setup-tests.js
import { configure } from '@testing-library/cypress';

configure({ testIdAttribute: 'data-cy' })

Option 2 — Configure it directly in the test, Cypress v9 and earlier: if you use an older Cypress version, configure the library in the test file:

// cypress/e2e/seu_teste.cy.js
import { configure } from '@testing-library/cypress';

// ...

describe('Seus testes', () => {
 before(() => {
 configure({ testIdAttribute: 'data-cy' })
 })

 // ... seus testes aqui
})

Option 3 — Create a new command:

Create a custom command that always uses findByTestId with data-cy:

// cypress/support/commands.js
Cypress.Commands.add('findByCy', (value, options) => {
 cy.findByTestId(value, { ...options, testIdAttribute: 'data-cy'})
})

References:

Testing Library

https://github.com/testing-library/cypress-testing-library/blob/97939da7d4707a71049884c0324c0eda56e26fc2/cypress/integration/find.spec.js

Cypress and Testing Library Link

Poor practices to avoid in test automation

Thu, 05 Jun 2025 00:00:00 +0000

Read this, print it, maybe print it and stick it on a few people’s computers…

1. Inadequate definition and planning

No clear goals: failing to clearly define the goal of automation, the risks, scope, and stakeholders. Automation without well-defined goals can waste effort and deliver disappointing results.

A poorly defined automation strategy: lacking a test automation strategy that is applicable, customizable, and kept up to date. A poorly defined strategy can produce inefficient tests that are difficult to maintain.

Ignoring investment criteria: overlooking factors such as initial cost, SDLC stage, project duration, and maintenance costs when deciding what to automate. Failing to analyze these can lead to inappropriate investment and a low return.

Not prioritizing tests: failing to prioritize the test conditions with the greatest business impact. Automation effort should focus on the tests that deliver the most value.

2. Technical problems

Poor SUT testability: automating a System Under Test that is not easily testable, making its interfaces difficult to access. Testability is essential for effective automation.

Poor automation architecture and framework: lacking a clear Test Automation Architecture, TAA, and a Test Automation Framework, TAF, that is easy to use and maintain. Poor architecture and frameworks make automated tests harder to implement and maintain.

Inadequate test reports: failing to generate well-defined reports, making troubleshooting and tracking results difficult. Without clear reports, effective decisions become harder.

No deployment and execution plan: lacking a clear plan for deploying and executing tests, removing tests when necessary, and handling exceptions effectively. Without these plans, tests may not run correctly or may cause execution problems.

Undocumented test cases: failing to document automated test cases adequately, making them difficult to understand and maintain. Clear documentation is crucial for maintenance and traceability.

3. Inappropriate automation choices and applications

Automating unsuitable tests: selecting cases without considering technical feasibility, coding effort, execution frequency, repeatability, and maintainability. Not every test is suitable for automation.

Automating difficult tests: trying to automate difficult conditions such as design validation, complex human interactions, and operating system restrictions. Some tests are more effective when performed manually.

Focusing only on user interface tests: building a strategy that relies primarily on UI tests, which are expensive and difficult to maintain. A balanced strategy should include component, contract, and API tests.

Not optimizing test distribution: failing to balance tests across component, service, and UI levels, which can make tests slow and expensive. A pyramid-shaped distribution can improve efficiency.

4. Ineffective transition and maintenance

Not monitoring costs: failing to track costs and test suite growth during the transition to continuous testing. Monitoring both is necessary for an efficient transition.

Functional overlap: writing test scripts with overlapping functionality, such as repeating the same login steps in different test cases. This makes maintenance harder and increases the required effort.

Inadequate data sharing: failing to manage shared test data correctly, introducing duplication or errors. Data should be stored and accessed from a single source.

Undocumented preconditions: failing to document and automate the preconditions required to run tests, leading to failures and inconsistencies. Defining and automating preconditions is essential for repeatability.

Not testing automated tests: forgetting that automation is software and needs testing too. Test scripts should be tested to ensure they work correctly.

Not refactoring automation: failing to assess and refactor the automation solution, allowing technical debt and maintenance difficulties to accumulate. Seek continuous improvements and optimization.

Not adapting the TAS to changes: failing to adapt the Test Automation Solution to new SUT versions. The TAS should be flexible enough to follow system changes.

5. Other poor practices

Excessive abstraction: using so much abstraction that automation code becomes hard to understand. Use abstraction in moderation to keep code understandable.

Complex data tables: creating very large, complex test data tables that make migration to other environments difficult. Manage test data efficiently.

Library dependencies: creating TAS dependencies on libraries or operating system components that may not be available everywhere. The TAS should be independent and portable across test environments.

Ignoring maintenance: failing to plan TAS maintenance as the SUT is updated. Continuous maintenance is essential to its effectiveness.

Not using metrics: failing to track pass/fail rates, failure and defect proportions, automation execution time, and functional and code coverage. These metrics help assess and optimize the TAS.

Not using test results to improve the process: failing to analyze report data to identify trends and improve the SDLC. Use test data for decisions and continuous improvement.

By Kellen Xavier | Contact

Applying design thinking to a real fitness studio website project

Thu, 24 Apr 2025 00:00:00 +0000

I am applying these studies to the strength training studio I attend in northern Porto Alegre. I asked the owner, who started the business in January 2025, for permission to apply the studies and develop a project for a real business with real needs.

The project: create a landing page for the studio, applying Design Thinking techniques and the material from Innovation and Entrepreneurship — Inovação e Empreendedorismo - Web 03.

Project beginnings: I followed the studio’s opening from January 2025. Since then, a close friend and I have been members training at the new location. The first things I asked the owner were: how will the gym work? Will there be flexible hours? Who will train here?

I tried to understand this better by talking to the owner of the strength training studio and asking these questions. Another important point is that I have trained there from the start. Since I knew the owner, I was the studio’s test member 😂. That helped the project because I experienced some important issues firsthand.

1. Empathy — Understand the problem from the user’s perspective

As a gym member, I ran into questions: what are the prices? How do the packages with nutritional support work? Are there partnerships with supplement stores? How much does whey protein cost? And others. I noticed that later members had the same questions. When recommending the gym, I also struggled to share its address and quote prices from memory. I only knew what I used myself, which was TotalPass. There was no central place to consult this information.

2. Define — Refine the problem

Based on this, I organized the information I had and talked to the owner to understand and refine the questions. Using design thinking techniques, I applied the Value Proposition Canvas to get the ideas out of my head and share them with the person involved: the business owner. See below:

I also used ChatGPT to structure the details and organize the information in the appropriate places, so I would not lose focus on the details.

ChatGPT

Below, I used a checklist of the information I had already mapped to stay organized throughout the process:

To make the interview clearer, I decided to create a form for the owner to answer. This corresponds to the “Define” stage mentioned and applied here.

3. Ideate

The ChatGPT output above gives us the following:

I will reorganize some points I consider important based on the needs mapped with the Value Proposition Canvas.

Landing page solution brainstorm, edited:

Organized sections: About us | Plans and advantages | Facilities | Booking and contact | FAQ.
A direct WhatsApp button.
High-quality photos of the space to build credibility.
A call to action highlighting the business’s distinguishing feature: a free fitness assessment.
A quick FAQ with questions raised by new users, collected through the form.

4. Prototype

I am terrible at design 😭, so I used Canva to bring this to life instead of letting that stop me.

Note: a quick reminder of the live class discussion: “Great, let’s go and do it.”

I do not know design.

5. Test

Creating the prototype: as mentioned, this prototype was made in Canva to visualize the planning from the Value Proposition Canvas. Below is the screen sequence:

Include the remaining service information once the form has been answered.

This initial prototype draft was developed to validate the owner’s needs for serving customers.

Building the prototype helped identify relevant points and, above all, represented significant progress by turning ideas into a practical, visual version. The process was quick and functional, helping guide the next steps.

The proposed continuation is to run more user tests and deploy the site in a real environment to assess whether the implemented features meet the previously mapped needs.

Canva prototype: link

Form research for better analysis and understanding

2. Design thinking questionnaire

For use in the Empathize and Define stages with the client.

Questions about the business

How would you describe your studio’s mission and values?
What is the main difference between your studio and other gyms?
Which services or advantages would you most like to highlight to new members?
What feeling or impression would you like members to have when visiting the studio?

Questions about customers

Who are your main customers today? Consider age, profile, and goals.
What do members praise most about your service?
What questions or concerns do prospective members most often express when contacting you?
What positive or negative feedback have you received about the gym experience?

Questions about communication

Which channels do you currently use to promote the studio? Instagram, WhatsApp, referrals, or others?

Questions about additional services

How does the nutritionist partnership work? Consider prices, appointments, and distinguishing features.
How does the supplement partnership work? Consider brands, discounts, and benefits.

Questions about experience

What benefits would you like to offer new members? Promotions, a trial class, or a first-month discount?

Reference links

See the website prototype: https://site-academia-app.vercel.app/

Website research for the fitness studio market — link.

Study references:

Product quality, Rian Dutra: LinkedIn
Book: Don’t Make Me Think, Steve Krug.
Book: The Design of Everyday Things, Donald A. Norman.
Book: Value Proposition Design, pages 142, 228, 232.
Unisinos postgraduate course: Innovation and Entrepreneurship classes with Professor Rosemary Francisco.
Tools: Canva and Vercel App for site deployment.
How to identify and solve user pain points in UX design
How to use storytelling in UX design

Website research for the fitness studio market

Thu, 17 Apr 2025 00:00:00 +0000

Studies and general analysis of gym websites

This brief research was carried out for a website prototype in the fitness sector. Its goal was to promote a studio focused on personal goals, aimed at people who dislike crowded gyms and a lack of instructor attention, prioritizing a personal approach to service.

1. Typical gym websites:

Gym websites are generally built around three main pillars:

Presenting services: showing the types of training available, such as strength training, functional training, spinning, Pilates, and yoga.
Attracting new members: highlighting promotions, plans, trial classes, and quick contact forms.
Social proof: displaying real photos, member testimonials, and results.

2. Common website structure:

An eye-catching homepage: images of people training, motivational messages, and the gym’s distinguishing features, such as 24-hour opening, a free fitness assessment, and parking.
Plans and pricing: many people want to find the monthly price quickly. Some sites show it; others require users to fill out a form first, which can cause them to leave.
Group class schedule: some gyms publish their weekly schedule on the website.
Location: an embedded map, usually Google Maps, is almost essential because location is a deciding factor.
Member area: some newer sites offer member logins for tracking workouts, payments, and physical progress.
Blog or health tips: uncommon, but useful for SEO and attracting more visitors through Google.
Direct chat or WhatsApp: many sites have floating buttons for quick WhatsApp contact.

3. How people search for gym websites:

Convenience: people want quick information. Slow sites or excessive forms lose users.
Comparison: users commonly open several nearby gym websites to compare prices, facilities, and distinguishing features.
Credibility: good photos, visible facilities, and real testimonials build trust.
Immediate benefits: free registration, a first-month discount, or a free trial class can be decisive.

4. SEO and traffic:

Many searches use local keywords, such as “gym in [city/neighborhood]” or “gym near me”.
Websites optimized for these searches are much more likely to be found organically, without paid advertising.

5. Design and current trends:

A clean, modern appearance without clutter.
Short homepage videos showing the space.
Integration with social media, especially Instagram.

Cypress and automation best practices

Thu, 24 Oct 2024 13:07:00 -0300

Avoiding false positives with Cypress. Below is an example of some code and a commands file with a simple application login:

This application was encountering an error during login. The following code was added to the automation to make login succeed:

But what does that code mean? It suppresses errors that occur in the application while Cypress tests run.

How? Using cy.on('uncaught:exception') and returning false tells Cypress to ignore errors in your application. This allows the test to continue even if the page has not fully loaded, giving elements time to render before Cypress tries to interact with them.

Why is removing cy.on('uncaught:exception') important? In this case, manipulating the test to ignore the error by returning false introduces a false positive. See below:

Alternatives for handling loading time and avoiding false positives

Instead of suppressing errors, use Cypress tools to ensure elements are present and ready for interaction before trying to access them. Some options include:

cy.wait(): wait for a specified time or for a particular element or condition before continuing the test.

Note: watch out for poor practices when using cy.wait(number). Read the documentation on this anti-pattern.

Unnecessary waiting

Instead, use:

cy.intercept('GET', '/users', [{ name: 'Maggy' }, { name: 'Joan' }]).as('getUsers')
cy.get('[data-testid="fetch-users"]').click()
cy.wait('@getUsers') // <--- wait explicitly for this route to finish

cy.get(...).should('exist') or

cy.get(...).should('be.visible')

Make sure the element exists and is visible on the page before trying to interact with it.