Best Practices for Testing with Brazilian Documents
Testing systems that accept Brazilian documents requires attention to algorithmic rules, edge cases, and legal compliance. This guide brings together best practices for QA teams and developers working with CPF, CNPJ, CNH, RG, and other documents.
Understand the documents your system accepts
The first step for correct testing is understanding the structure of each document accepted by the system. CPF and CNPJ have check digits calculated by modulus 11. CNH has its own check digit. RENAVAM uses modulus 11 with specific weights. RG has no single national rule — each state has its own format. Credit cards use the Luhn algorithm (modulus 10). Knowing these rules allows you to create precise test cases.
For each document type, document: (1) expected format with and without mask; (2) digit length; (3) check digit rules; (4) known invalidity cases (all identical digits, for example); (5) regional variations where applicable. This documentation becomes the basis of your test plan.
Covering the most important edge cases
Edge cases for document validation are predictable and should be part of every test plan: (1) Empty or null document — is the field required? (2) Incorrect length — fewer or more digits than expected. (3) Non-numeric characters — letters, symbols, spaces. (4) Incorrect check digits — number with valid structure but wrong verifier. (5) Sequences invalid by definition — such as CPFs with all identical digits. (6) Masks — does the system accept '123.456.789-09' and '12345678909' as equivalent?
(7) State-specific documents — for Voter Title and AIH, test with valid and invalid state codes. (8) Boundary values — for documents with valid ranges (like CNPJ where the suffix 0000 may be invalid). (9) SQL injection and XSS — document fields are a common attack vector; validate that malicious inputs are handled correctly before document validation.
Structuring efficient automated tests
In frameworks like Cypress, Playwright, or Selenium, organize document tests in three categories: field validation tests (unit), flow tests with valid data (integration), and flow tests with invalid data (negative). For negative tests, use a fixture with known invalid documents — keep this list in the repository.
Parameterize your field tests with multiple valid documents to increase coverage without multiplying code. A single parameterized test with 10 different valid CPFs covers much more than 10 identical tests. Help4Dev can be used during test development to quickly generate the necessary data.
Test data and environment management
Separate test data by environment: development, QA, staging, and production should have distinct data sets. In development and QA, use exclusively fictitious data. In staging, use fictitious data that mimics real customer patterns (same geographic distribution, for example). Never use real production data in non-production environments.
Version your test data alongside the code in the repository. A seeds.json or fixtures/documents.json file with valid fictitious CPFs, CNPJs, and other data ensures everyone on the team uses the same data and that CI/CD pipelines work consistently. Update these files whenever you add new document types to the system.
Common mistakes and how to avoid them
The most frequent mistakes in Brazilian document testing: (1) Using famous internet CPFs — there are fictitious CPFs widely shared online (like 123.456.789-09) that are well-known and may have special behavior in some legacy systems. Prefer randomly generated data. (2) Not testing masks — systems often accept or reject documents based on the presence or absence of punctuation; test both formats. (3) Ignoring backend validation — always validate on the server, even if you validate on the frontend.
(4) Reusing the same CPF in many tests — if the system does not allow two registrations with the same CPF, always using the same data will cause false negatives. Generate varied data. (5) Not updating test data after rule changes — the alphanumeric CNPJ is a good example: when the change takes effect, existing tests will need to cover the new format. Maintain a process to review and update test data periodically.