O WordPress Playground costuma ser usado como um ambiente isolado e descartável no navegador: abra um link, teste um plugin e feche a aba.

Isso é útil, mas o desenvolvimento de plugins e temas geralmente envolve mais de um ambiente isolado. Você pode precisar de um site limpo para reproduzir um problema, de um site salvo para continuar a depuração, de outro site configurado com uma versão diferente do PHP e de uma forma de inspecionar todos eles sem navegar pela interface.

Atualizações recentes do Playground facilitam a automação desses fluxos de trabalho. O site do Playground agora disponibiliza um objeto de gerenciamento de sites para o JavaScript executado na página principal. O código no console do navegador ou em uma ferramenta de automação pode acessar esse objeto por meio de window.playgroundSites para listar e alternar entre sites, salvar sites temporários, renomear sites salvos, alterar configurações do ambiente de execução ou obter o PlaygroundClient do site ativo.

Este post mostra como quem desenvolve plugins e temas pode usar essa API no console do navegador para agilizar tarefas do dia a dia.

Antes dessas atualizações, tudo o que ficava fora da interface do Playground precisava recriar o comportamento de gerenciamento de sites. Ferramentas MCP, o WebMCP nativo do navegador, experimentos no DevTools e componentes da interface precisavam de uma forma de listar, salvar, renomear ou alternar entre sites.

A nova PlaygroundSitesAPI oferece uma interface compartilhada para esses fluxos de trabalho. Depois que o site do Playground carrega, o JavaScript executado na página pode chamar essa interface por meio de window.playgroundSites. Isso permite gerenciar sites com código sem depender de uma automação frágil da interface.

Na prática, agora você pode abrir o DevTools e executar:

window.playgroundSites.list();

O resultado é um array de registros de sites:

[
  {
    slug: "quiet-river",
    name: "Quiet River",
    storage: "temporary",
    isActive: true,
  },
];

O campo storage indica se o site é temporário, está salvo no armazenamento do navegador ou está salvo no sistema de arquivos local. Sites temporários desaparecem quando a página é recarregada, a menos que você os salve primeiro.

Os fluxos de trabalho deste post usam estes métodos principais:

A API fica disponível depois que o Playground carrega os sites salvos. Se window.playgroundSites estiver indefinido, aguarde até que a interface do Playground termine de carregar. Em seguida, chame await window.playgroundSites.isReady() antes de executar comandos que dependem do cliente do site ativo.

Consulte a documentação da Sites API para ver a referência completa, incluindo métodos relacionados ao salvamento automático e ao salvamento explícito.

Os exemplos a seguir usam a Sites API em playground.wordpress.net. Abra o site, aguarde o carregamento da interface do Playground, abra o console do DevTools do navegador e execute await window.playgroundSites.isReady(). Depois, cole os exemplos no console. Uma ferramenta de automação de navegador, como o Playwright, pode executar o mesmo JavaScript enquanto controla uma aba aberta no site do Playground.

Essa API faz parte do site do Playground. Ela não faz parte do pacote @wp-playground/client nem da Playground CLI e não é exposta por /remote.html quando você incorpora o Playground a outro aplicativo. Para sites incorporados e automações de teste que inicializam o próprio cliente do Playground, use a API JavaScript.

Ao depurar um problema de plugin, comece com um site novo que corresponda ao ambiente desejado. O exemplo a seguir cria um site temporário com PHP 8.4, a versão mais recente do WordPress e acesso à rede ativado:

const slug = await window.playgroundSites.createNewTemporarySite(
  "plugin-test-php-84",
  {
    phpVersion: "8.4",
    wpVersion: "latest",
    networking: true,
  }
);

console.log(`Active test site: ${slug}`);

Use essa opção quando precisar de um ambiente limpo antes de instalar um plugin ou reproduzir um problema relatado. Neste momento, o site é temporário, portanto as alterações não persistem depois que a página é recarregada.

Depois de reproduzir o erro, salve o site antes de fazer outras alterações. O salvamento transforma um site temporário em um site armazenado no navegador:

const saved = await window.playgroundSites.saveInBrowser(
  "Plugin compatibility test"
);

console.log(saved);

O objeto retornado inclui o slug e o tipo de armazenamento do site:

{
  slug: "plugin-test-php-84",
  storage: "opfs",
}

Depois de salvar, você pode renomear o site ativo:

await window.playgroundSites.rename(
  "Plugin compatibility test - PHP 8.4"
);

A ordem é importante. rename() funciona apenas com sites salvos. Se você chamar o método em um site temporário, o Playground gera este erro:

Cannot rename a temporary site. Save it first.

Ao manter sites separados para diferentes casos de reprodução, liste-os e alterne entre eles pelo slug:

const sites = window.playgroundSites.list();

console.table(
  sites.map((site) => ({
    slug: site.slug,
    name: site.name,
    storage: site.storage,
    active: site.isActive,
  }))
);

Para ativar um deles:

const target = window.playgroundSites
  .list()
  .find((site) => site.name.includes("Plugin compatibility"));

if (target) {
  await window.playgroundSites.setActiveSite(target.slug);
}

O método setActiveSite() aguarda a inicialização do site selecionado antes de concluir. Assim, os comandos seguintes podem pressupor com segurança que o site ativo está pronto.

A API de gerenciamento de sites dá acesso ao PlaygroundClient do site ativo. Esse cliente pode executar PHP no ambiente do WordPress.

function phpResponseText(response) {
  return "text" in response
    ? response.text
    : new TextDecoder().decode(response.bytes);
}

await window.playgroundSites.isReady();
const client = window.playgroundSites.getClient();

if (!client) {
  throw new Error("The active Playground site has not booted yet.");
}

const response = await client.run({
  code: `<?php
require_once "/wordpress/wp-load.php";

echo json_encode([
  "php" => phpversion(),
  "wp" => get_bloginfo("version"),
  "active_plugins" => get_option("active_plugins"),
]);
`,
});

console.log(phpResponseText(response));

Com isso, você pode consultar diretamente no banco de dados do WordPress os dados de um plugin, sem navegar pelo wp-admin. Substitua o PHP por verificações específicas de opções, dados do tema ativo, tipos de post personalizados ou linhas específicas do plugin no banco de dados.

Por exemplo, para inspecionar uma opção:

const response = await client.run({
  code: `<?php
require_once "/wordpress/wp-load.php";
echo wp_json_encode(get_option("woocommerce_currency"));
`,
});

console.log(phpResponseText(response));

O Playground usa SQLite para armazenamento no WordPress. Portanto, prefira APIs do WordPress, como get_option() e $wpdbem vez de depender de comportamentos específicos de SQL de um banco de dados.

Às vezes, um erro ocorre apenas com uma versão específica do PHP ou com o acesso à rede ativado. Depois que o site ativo estiver salvo, você pode atualizar diretamente as configurações do ambiente de execução:

await window.playgroundSites.setPhpVersion("8.3");
await window.playgroundSites.setNetworking(true);

Esses métodos exigem um site salvo. Se o site ativo for temporário, salve-o primeiro:

await window.playgroundSites.saveInBrowser("Network test");
await window.playgroundSites.setNetworking(true);

Este é um bom fluxo de trabalho para testes de compatibilidade:

1. Crie um site limpo.
2. Instale e configure o plugin.
3. Salve o site.
4. Alterne entre versões do PHP.
5. Execute novamente as mesmas verificações do plugin.

Você pode combinar as chamadas da API em uma lista de verificação manual no DevTools. Este exemplo cria e salva um site, coleta informações básicas de versão e deixa o resultado no console:

async function prepareCompatibilitySite() {
  function phpResponseText(response) {
    return "text" in response
      ? response.text
      : new TextDecoder().decode(response.bytes);
  }

  const slug = await window.playgroundSites.createNewTemporarySite(
    "compatibility-check",
    {
      phpVersion: "8.4",
      wpVersion: "latest",
      networking: true,
    }
  );

  await window.playgroundSites.saveInBrowser(
    "Compatibility check - PHP 8.4"
  );

  await window.playgroundSites.isReady();
  const client = window.playgroundSites.getClient();
  if (!client) {
    throw new Error("The compatibility site has not booted yet.");
  }

  const response = await client.run({
    code: `<?php
require_once "/wordpress/wp-load.php";
echo wp_json_encode([
  "site_url" => get_site_url(),
  "php" => phpversion(),
  "wp" => get_bloginfo("version"),
  "theme" => wp_get_theme()->get("Name"),
]);
`,
  });

  return {
    site: window.playgroundSites
      .list()
      .find((site) => site.slug === slug),
    info: JSON.parse(phpResponseText(response)),
  };
}

console.log(await prepareCompatibilitySite());

Isso não substitui um conjunto completo de testes. É uma forma rápida de preparar e inspecionar um site de teste no navegador durante a triagem de um problema relatado.

Atualizações recentes do Playground também adicionaram pontos de integração mais completos com IA e automação do navegador por meio de MCP e WebMCP. A mesma API centralizada de gerenciamento de sites oferece suporte a essas integrações. Assim, agentes de IA e ferramentas nativas do navegador podem gerenciar sites do Playground por meio de operações explícitas, em vez de clicar em menus.

Por exemplo:

• list() corresponde naturalmente a “mostre meus sites do Playground”.
• setActiveSite(slug) corresponde a “abra o site chamado Plugin compatibility test”.
• saveInBrowser(name) corresponde a “salve esta reprodução para que eu possa retomá-la depois”.
• getClient() dá às ferramentas acesso à execução de PHP, a solicitações HTTP e a operações no sistema de arquivos.

O resultado é uma base mais simples para os fluxos de trabalho de agentes. Um agente de programação pode manter um site para investigação, outro para uma reprodução limpa e mais um para verificar uma correção, sem depender do estado visual da interface.

Para ver as instruções de configuração, consulte Conecte agentes de programação ao WordPress Playground com MCP. Para ver as opções de configuração baseadas em URL, como php, wp, networking e site-slug, consulte a documentação da Query API.

Considere estes detalhes:

• window.playgroundSites fica disponível somente depois que o Playground termina de carregar os sites salvos.
• Sites temporários precisam ser salvos antes que você possa renomeá-los, excluí-los ou atualizar suas configurações de PHP e rede.
• Chame isReady() antes de getClient() quando o site ativo ainda puder estar em inicialização. Até que o site esteja pronto, getClient() pode retornar undefined.
• saveToLocalFileSystem() pode abrir um seletor de diretório do navegador quando você não fornece uma referência ao diretório.
• O armazenamento do navegador continua sujeito às limitações do navegador. Limpar os dados do site pode remover sites salvos do Playground.

Abra playground.wordpress.net, aguarde o carregamento do site, abra o DevTools e execute:

await window.playgroundSites.isReady();
window.playgroundSites.list();

Depois, crie um site temporário, salve-o, alterne entre sites salvos e use getClient() para inspecionar o estado do WordPress com PHP. Para quem desenvolve plugins e temas, isso transforma o Playground de um único ambiente isolado em um conjunto de ambientes de teste no navegador.